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/coldstart/sources.py

View on GitHub
#!/usr/bin/env python3
"""Source-tier scanning and structured proposal synthesis for cold start."""

from __future__ import annotations

import re
import subprocess
from pathlib import Path

from core.protocol.contracts import validate_workspace_language

ROOT_ENTRY_CANDIDATES = (
    Path("README.md"),
    Path("README.en.md"),
    Path("README.zh-CN.md"),
    Path("AGENTS.md"),
    Path("CLAUDE.md"),
    Path("GEMINI.md"),
    Path(".github/copilot-instructions.md"),
)

HIGH_SIGNAL_DOC_RE = re.compile(r"(change ?log|spec|roadmap|architecture)", re.I)
USER_REALITY_DOC_RE = re.compile(r"(memory|status|summary|handoff|decision|milestone|progress)", re.I)
MARKDOWN_HEADING_RE = re.compile(r"^\s{0,3}#{1,6}\s+")
HOST_MEMORY_CONFIDENCE_LEVELS = {"low", "medium", "high"}
HOST_MEMORY_PATH_REF = "host-memory:path"
HOST_MEMORY_COMMAND_REF = "host-memory:command"
HOST_MEMORY_PATH_PLACEHOLDER = (
    "Host memory path declared explicitly as hint-only; contents are not copied into public output."
)
HOST_MEMORY_COMMAND_PLACEHOLDER = (
    "Host memory command declared explicitly but not executed automatically."
)
HOST_MEMORY_SOURCE_MAX_LENGTH = 64
_HOST_MEMORY_SOURCE_SAFE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+ -]{0,63}$")
_HOST_MEMORY_SOURCE_URL_RE = re.compile(r"(?i)\b(?:https?|file)://")
_HOST_MEMORY_SOURCE_EMAIL_RE = re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")
_HOST_MEMORY_SOURCE_SECRET_RE = re.compile(
    r"(?i)(?:\b(?:api[_-]?key|token|secret|password|credential)\b|"
    r"\bsk-[A-Za-z0-9]{8,}\b|"
    r"\bghp_[A-Za-z0-9_]{8,}\b|"
    r"\bgithub_pat_[A-Za-z0-9_]{8,}\b|"
    r"\bbearer\s+[A-Za-z0-9._-]+)"
)
_HOST_MEMORY_SOURCE_PRIVATE_WORD_RE = re.compile(
    r"(?i)(?:^|[._ +\-])(?:account|acct|tenant|workspace|user|profile|private|session|sid|transcript|conversation|thread|trace)(?=[A-Za-z0-9._ +\-]|$)"
)


def _resolved_path_within_project(candidate: Path, *, project_root: Path) -> Path | None:
    try:
        resolved_candidate = candidate.resolve(strict=True)
        resolved_project_root = project_root.resolve(strict=True)
    except OSError:
        return None
    try:
        resolved_candidate.relative_to(resolved_project_root)
    except ValueError:
        return None
    return resolved_candidate


def _dedupe_internal_project_candidates(
    candidates: list[Path],
    *,
    project_root: Path,
) -> list[tuple[Path, Path]]:
    accepted: dict[str, dict[str, object]] = {}
    for index, candidate in enumerate(candidates):
        resolved_candidate = _resolved_path_within_project(
            candidate,
            project_root=project_root,
        )
        if not candidate.is_file() or resolved_candidate is None:
            continue
        resolved_key = resolved_candidate.as_posix()
        existing = accepted.get(resolved_key)
        if existing is None:
            accepted[resolved_key] = {
                "candidate": candidate,
                "resolved_candidate": resolved_candidate,
                "index": index,
            }
            continue
        existing_candidate = existing["candidate"]
        if isinstance(existing_candidate, Path) and existing_candidate.is_symlink() and not candidate.is_symlink():
            existing["candidate"] = candidate
            existing["resolved_candidate"] = resolved_candidate
    return [
        (entry["candidate"], entry["resolved_candidate"])
        for entry in sorted(accepted.values(), key=lambda item: int(item["index"]))
        if isinstance(entry["candidate"], Path) and isinstance(entry["resolved_candidate"], Path)
    ]


def normalize_text_lines(text: str, *, max_lines: int = 4) -> list[str]:
    lines: list[str] = []
    for raw in text.splitlines():
        stripped = raw.strip()
        if not stripped:
            continue
        if stripped.startswith("<!--"):
            continue
        if MARKDOWN_HEADING_RE.match(stripped):
            continue
        stripped = stripped.lstrip("-* ").strip()
        if not stripped:
            continue
        lines.append(stripped)
        if len(lines) >= max_lines:
            break
    return lines


def read_source_excerpt(path: Path, *, max_lines: int = 4) -> list[str]:
    try:
        return normalize_text_lines(path.read_text(encoding="utf-8"), max_lines=max_lines)
    except (OSError, UnicodeDecodeError):
        return []


def sanitize_host_memory_source_label(source_label: str | None) -> str:
    if not source_label or not source_label.strip():
        raise ValueError("Enabling host memory requires --host-memory-source.")
    normalized = source_label.strip()
    if len(normalized) > HOST_MEMORY_SOURCE_MAX_LENGTH:
        raise ValueError("Host memory source label must be a short public-safe host label.")
    if (
        _HOST_MEMORY_SOURCE_EMAIL_RE.search(normalized)
        or _HOST_MEMORY_SOURCE_URL_RE.search(normalized)
        or _HOST_MEMORY_SOURCE_SECRET_RE.search(normalized)
        or _HOST_MEMORY_SOURCE_PRIVATE_WORD_RE.search(normalized)
        or "/" in normalized
        or "\\" in normalized
        or not _HOST_MEMORY_SOURCE_SAFE_RE.fullmatch(normalized)
    ):
        raise ValueError("Host memory source label must be a short public-safe host label.")
    return normalized


def tier_a_sources(project_root: Path) -> list[dict]:
    sources: list[dict] = []
    candidates = [project_root / rel_path for rel_path in ROOT_ENTRY_CANDIDATES]
    for candidate, _resolved_candidate in _dedupe_internal_project_candidates(
        candidates,
        project_root=project_root,
    ):
        rel_path = candidate.relative_to(project_root)
        sources.append(
            {
                "tier": "A",
                "path": str(candidate),
                "relative_path": rel_path.as_posix(),
                "kind": "root_entry",
                "confidence": "high",
                "excerpt_lines": read_source_excerpt(candidate),
            }
        )
    return sources


def tier_b_sources(project_root: Path) -> list[dict]:
    sources: list[dict] = []
    docs_dir = project_root / "docs"
    candidates: list[Path] = []
    if docs_dir.is_dir():
        for candidate in sorted(docs_dir.rglob("*")):
            if not HIGH_SIGNAL_DOC_RE.search(candidate.stem):
                continue
            candidates.append(candidate)
    for candidate in sorted(project_root.iterdir()):
        if not HIGH_SIGNAL_DOC_RE.search(candidate.stem):
            continue
        candidates.append(candidate)
    for candidate, _resolved_candidate in _dedupe_internal_project_candidates(
        candidates,
        project_root=project_root,
    ):
        rel = candidate.relative_to(project_root).as_posix()
        sources.append(
            {
                "tier": "B",
                "path": str(candidate),
                "relative_path": rel,
                "kind": "high_signal_doc",
                "confidence": "medium",
                "excerpt_lines": read_source_excerpt(candidate),
            }
        )
    return sources


def tier_c_sources(project_root: Path) -> list[dict]:
    candidates = list(project_root.glob("*.md"))
    docs_dir = project_root / "docs"
    if docs_dir.is_dir():
        candidates.extend(docs_dir.rglob("*.md"))

    filtered_candidates = [
        candidate
        for candidate in sorted(candidates, key=lambda path: path.as_posix())
        if USER_REALITY_DOC_RE.search(candidate.stem)
    ]

    sources: list[dict] = []
    for candidate, _resolved_candidate in _dedupe_internal_project_candidates(
        filtered_candidates,
        project_root=project_root,
    ):
        rel = candidate.relative_to(project_root).as_posix()
        sources.append(
            {
                "tier": "C",
                "path": str(candidate),
                "relative_path": rel,
                "kind": "user_reality_doc",
                "confidence": "medium",
                "excerpt_lines": read_source_excerpt(candidate),
            }
        )
    return sources


def tier_d_sources(project_root: Path, explicit_sources: list[str]) -> list[dict]:
    sources: list[dict] = []
    missing_count = 0
    try:
        project_resolved = project_root.resolve(strict=True)
    except OSError:
        project_resolved = project_root.resolve()
    for raw in explicit_sources:
        candidate = Path(raw).expanduser()
        if not candidate.is_absolute():
            candidate = (project_root / candidate).resolve()
        if not candidate.is_file():
            missing_count += 1
            continue
        try:
            resolved_candidate = candidate.resolve(strict=True)
            relative_path = resolved_candidate.relative_to(project_resolved).as_posix()
            path_ref = str(resolved_candidate)
            excerpt_lines = read_source_excerpt(resolved_candidate)
        except ValueError:
            relative_path = "external-source"
            path_ref = "explicit-source:external"
            excerpt_lines = []
        except OSError:
            missing_count += 1
            continue
        sources.append(
            {
                "tier": "D",
                "path": path_ref,
                "relative_path": relative_path,
                "kind": "explicit_source",
                "confidence": "high",
                "excerpt_lines": excerpt_lines,
            }
        )
    if missing_count:
        raise ValueError("One or more explicit Tier-D source paths must exist as regular files.")
    return sources


def tier_e_sources(project_root: Path, *, include_git_signal: bool, max_commits: int = 5) -> list[dict]:
    if not include_git_signal:
        return []
    try:
        proc = subprocess.run(
            ["git", "-C", str(project_root), "log", f"-n{max_commits}", "--pretty=%s"],
            text=True,
            capture_output=True,
            check=False,
        )
    except OSError:
        return []
    if proc.returncode != 0:
        return []
    lines = [line.strip() for line in proc.stdout.splitlines() if line.strip()]
    if not lines:
        return []
    return [
        {
            "tier": "E",
            "path": f"git:{index + 1}",
            "relative_path": f"git:{index + 1}",
            "kind": "recent_commit_subject",
            "confidence": "low",
            "excerpt_lines": [line],
        }
        for index, line in enumerate(lines)
    ]


def build_host_memory_adapter(
    project_root: Path,
    *,
    enabled: bool,
    source_label: str | None,
    path_raw: str | None,
    command_raw: str | None,
    confidence: str | None,
) -> dict:
    if not enabled:
        return {
            "enabled": False,
            "source": None,
            "mode": None,
            "path": None,
            "command": None,
            "confidence": None,
            "hint_only": True,
            "ingested": False,
            "error": None,
        }

    safe_source_label = sanitize_host_memory_source_label(source_label)
    if confidence not in HOST_MEMORY_CONFIDENCE_LEVELS:
        raise ValueError(
            "Enabling host memory requires --host-memory-confidence with one of: low, medium, high."
        )
    provided = [bool(path_raw), bool(command_raw)]
    if sum(provided) != 1:
        raise ValueError(
            "Enabling host memory requires exactly one of --host-memory-path or --host-memory-command."
        )

    if path_raw:
        candidate = Path(path_raw).expanduser()
        if not candidate.is_absolute():
            candidate = (project_root / candidate).resolve()
        if not candidate.is_file():
            raise ValueError("Host memory path does not exist or is not a regular file.")
        return {
            "enabled": True,
            "source": safe_source_label,
            "mode": "path",
            "path": HOST_MEMORY_PATH_REF,
            "command": None,
            "confidence": confidence,
            "hint_only": True,
            "ingested": False,
            "error": None,
        }

    return {
        "enabled": True,
        "source": safe_source_label,
        "mode": "command",
        "path": None,
        "command": HOST_MEMORY_COMMAND_REF,
        "confidence": confidence,
        "hint_only": True,
        "ingested": False,
        "error": None,
    }


def tier_f_sources(project_root: Path, adapter: dict) -> list[dict]:
    if not adapter.get("enabled"):
        return []
    if adapter.get("mode") == "path" and adapter.get("path"):
        return [
            {
                "tier": "F",
                "path": HOST_MEMORY_PATH_REF,
                "relative_path": HOST_MEMORY_PATH_REF,
                "kind": "host_memory_path",
                "confidence": adapter["confidence"],
                "hint_only": True,
                "excerpt_lines": [HOST_MEMORY_PATH_PLACEHOLDER],
            }
        ]
    return [
        {
            "tier": "F",
            "path": HOST_MEMORY_COMMAND_REF,
            "relative_path": HOST_MEMORY_COMMAND_REF,
            "kind": "host_memory_command",
            "confidence": adapter["confidence"],
            "hint_only": True,
            "excerpt_lines": [HOST_MEMORY_COMMAND_PLACEHOLDER],
        }
    ]


def gather_coldstart_sources(
    project_root: Path,
    *,
    explicit_sources: list[str] | None = None,
    include_git_signal: bool = False,
    host_memory_adapter: dict | None = None,
) -> list[dict]:
    explicit_sources = explicit_sources or []
    host_memory_adapter = host_memory_adapter or {
        "enabled": False,
        "hint_only": True,
    }
    sources: list[dict] = []
    sources.extend(tier_a_sources(project_root))
    sources.extend(tier_b_sources(project_root))
    sources.extend(tier_c_sources(project_root))
    sources.extend(tier_d_sources(project_root, explicit_sources))
    sources.extend(tier_e_sources(project_root, include_git_signal=include_git_signal))
    sources.extend(tier_f_sources(project_root, host_memory_adapter))
    return sources


def _merge_excerpt_lines(sources: list[dict], *, tiers: tuple[str, ...], max_lines: int = 4) -> list[str]:
    lines: list[str] = []
    for source in sources:
        if source["tier"] not in tiers:
            continue
        for line in source.get("excerpt_lines", []):
            if line not in lines:
                lines.append(line)
            if len(lines) >= max_lines:
                return lines
    return lines


def _localized_coldstart_strings(language: str) -> dict[str, object]:
    if language == "zh-CN":
        return {
            "source_line": "- 第 {tier} 层 | {confidence} | {relative_path}",
            "fallback_background": "扫描到的来源还不足以明确背景,需要人工审阅。",
            "fallback_current_state": "扫描到的来源尚未明确当前状态,需要人工审阅。",
            "fallback_milestones": "扫描到的来源里没有发现明确的里程碑证据。",
            "fallback_next_step": "下一步尚不明确,提升前需要人工审阅。",
            "tier_f_disabled": "第 F 层 host-memory 来源默认关闭,且本次未读取。",
            "tier_f_path": (
                "第 F 层 host-memory 来源以显式的仅提示输入纳入,但仍需要人工审阅。"
            ),
            "tier_f_command": (
                "第 F 层 host-memory command 元数据以仅提示输入纳入;命令本身没有被自动执行。"
            ),
            "uncertainty_generated": "该提案是基于文件摘录的启发式结果,仍需要人工审阅。",
            "uncertainty_used_tiers": "使用层级:{tiers}。",
            "promotion_lines": [
                "- context_brief.md:适合承载持久的项目背景、范围和事实来源",
                "- rolling_summary.md:适合承载当前状态、下一步和当前判断",
                "- daily_logs/:仅在值得长期保留时记录里程碑证据",
            ],
            "review_before_promotion": "- 提升前需要人工审阅。",
            "generated_from": "- 本提案基于 {count} 个来源生成。",
            "no_eligible_sources": "- 没有发现符合条件的来源。",
            "no_judgment_reversals": "- 没有自动推断出判断反转。",
            "section_headings": [
                "来源摘要",
                "来源类型与可信级别",
                "候选当前状态事实",
                "候选里程碑事件",
                "候选判断反转",
                "候选下一步变化",
                "与当前 sidecar 的冲突",
                "建议提升动作",
                "审阅结论",
            ],
        }
    return {
        "source_line": "- Tier {tier} | {confidence} | {relative_path}",
        "fallback_background": "Unclear from scanned sources; needs review.",
        "fallback_current_state": "Current state is not yet explicit in the scanned sources; needs review.",
        "fallback_milestones": "No clear milestone evidence was found in the scanned sources.",
        "fallback_next_step": "Next step is not explicit; review manually before promotion.",
        "tier_f_disabled": "Tier F host-memory sources are disabled by default and were not read.",
        "tier_f_path": (
            "Tier F host-memory sources were included as explicit hint-only inputs and still require manual review."
        ),
        "tier_f_command": (
            "Tier F host-memory command metadata was included as hint-only input; the command was not auto-executed."
        ),
        "uncertainty_generated": "Proposal is generated heuristically from file excerpts and still requires review.",
        "uncertainty_used_tiers": "Used tiers: {tiers}.",
        "promotion_lines": [
            "- context_brief.md: durable project background, scope, and source-of-truth facts",
            "- rolling_summary.md: current state, next step, and active judgments",
            "- daily_logs/: milestone evidence only if worth long-term retention",
        ],
        "review_before_promotion": "- Review before promotion.",
        "generated_from": "- Generated from {count} source(s).",
        "no_eligible_sources": "- No eligible sources were found.",
        "no_judgment_reversals": "- No judgment reversals were inferred automatically.",
        "section_headings": [
            "source summary",
            "source type and confidence",
            "candidate current-state facts",
            "candidate milestone events",
            "candidate judgment reversals",
            "candidate next-step changes",
            "conflicts with current sidecar",
            "suggested promotion actions",
            "review conclusion",
        ],
    }


def render_coldstart_proposal(project_root: Path, sources: list[dict], *, workspace_language: str) -> str:
    language = validate_workspace_language(workspace_language)
    strings = _localized_coldstart_strings(language)
    tiers_used = sorted({source["tier"] for source in sources})
    tier_f_sources = [source for source in sources if source["tier"] == "F"]
    source_lines = [
        str(strings["source_line"]).format(
            tier=source["tier"],
            confidence=source["confidence"],
            relative_path=source["relative_path"],
        )
        for source in sources
    ]
    background_lines = _merge_excerpt_lines(sources, tiers=("A", "B"), max_lines=4) or [
        strings["fallback_background"]
    ]
    current_state_lines = _merge_excerpt_lines(sources, tiers=("C", "D"), max_lines=4) or [
        strings["fallback_current_state"]
    ]
    milestone_lines = _merge_excerpt_lines(sources, tiers=("B", "E"), max_lines=4) or [
        strings["fallback_milestones"]
    ]
    next_step_lines = _merge_excerpt_lines(sources, tiers=("C", "D", "E"), max_lines=3) or [
        strings["fallback_next_step"]
    ]
    tier_f_note = strings["tier_f_disabled"]
    if tier_f_sources:
        if any(source.get("kind") == "host_memory_path" for source in tier_f_sources):
            tier_f_note = strings["tier_f_path"]
        else:
            tier_f_note = strings["tier_f_command"]
    uncertainty_lines = [
        strings["uncertainty_generated"],
        str(strings["uncertainty_used_tiers"]).format(tiers=", ".join(tiers_used) if tiers_used else "none"),
        tier_f_note,
    ]
    promotion_lines = list(strings["promotion_lines"])
    headings = list(strings["section_headings"])

    sections = [
        (headings[0], [str(strings["generated_from"]).format(count=len(sources)), *background_lines[:2]]),
        (headings[1], source_lines or [strings["no_eligible_sources"]]),
        (headings[2], [*background_lines, *current_state_lines]),
        (headings[3], milestone_lines),
        (headings[4], [strings["no_judgment_reversals"]]),
        (headings[5], next_step_lines),
        (headings[6], [f"- {line}" for line in uncertainty_lines]),
        (headings[7], promotion_lines),
        (headings[8], [strings["review_before_promotion"]]),
    ]

    parts: list[str] = []
    for heading, lines in sections:
        parts.append(f"## {heading}")
        parts.extend(lines)
        parts.append("")
    return "\n".join(parts).rstrip() + "\n"


def recommend_coldstart_path(sources: list[dict]) -> dict:
    tiers = {source["tier"] for source in sources}
    has_current_state_signal = any(source["tier"] in {"C", "D"} and source.get("excerpt_lines") for source in sources)
    has_core_project_signal = any(source["tier"] in {"A", "B"} and source.get("excerpt_lines") for source in sources)
    uses_host_memory = "F" in tiers
    uses_explicit_or_git = bool({"D", "E"} & tiers)

    fast_path = has_core_project_signal and has_current_state_signal and not uses_host_memory
    if fast_path:
        reasoning = [
            "Tier A/B project framing and Tier C/D current-state signals are both present.",
            "No host-memory fallback was needed for the default path.",
        ]
        if uses_explicit_or_git:
            reasoning.append("Tier D/E supplemental signals exist but do not by themselves force a deep path.")
        return {
            "interaction_mode": "fast_path",
            "needs_deep_review": False,
            "reasoning": reasoning,
        }

    reasoning = []
    if not has_core_project_signal:
        reasoning.append("Project framing sources are insufficient for a low-ambiguity cold start.")
    if not has_current_state_signal:
        reasoning.append("Current-state signals are insufficient to seed continuity safely.")
    if uses_host_memory:
        reasoning.append("Host memory is hint-only and should trigger explicit review before promotion.")
    if not reasoning:
        reasoning.append("Cold-start proposal still requires explicit review because source coverage is ambiguous.")
    return {
        "interaction_mode": "deep_path",
        "needs_deep_review": True,
        "reasoning": reasoning,
    }
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