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

View on GitHub
#!/usr/bin/env python3
"""Safely append a milestone entry to a RecallLoom daily log."""

from __future__ import annotations

import argparse
from datetime import date, datetime
import json
from pathlib import Path

from core.continuity.workday import (
    DEFAULT_LOGICAL_WORKDAY_ROLLOVER_HOUR,
    logical_workday_for,
)
from core.failure.context import (
    COMMAND_APPEND,
    OPERATION_DAILY_LOG_APPEND,
    STAGE_PREFLIGHT,
    OperationContext,
)
from core.failure.contracts import failure_payload
from core.output.privacy import publicize_json_value
from core.protocol.contracts import FILE_KEYS
from core.provenance.bindings import (
    PreflightBindingLeaseError,
    verify_preflight_binding_lease,
)
from core.provenance.receipts import assert_public_safe_json, public_receipt_claim
from core.provenance.state import (
    provenance_contract_identity,
    preflight_write_binding_hash,
)
from core.recording import daily_log_append
from core.recording import transaction as recording_transaction
from core.safety import input_transport

from _common import (
    cli_failure_payload,
    cli_failure_payload_for_exception,
    ConfigContractError,
    DAILY_LOGS_DIRNAME,
    DailyLogCursorError,
    EnvironmentContractError,
    StorageResolutionError,
    daily_log_cursors_equivalent,
    daily_log_cursor_from_text,
    daily_log_cursor_is_legacy_empty,
    daily_log_cursor_state_fields,
    detect_update_protocol_time_policy_cues,
    enforce_package_support_gate,
    ensure_supported_python_version,
    exit_if_startup_scratch_residue_for_sources,
    exit_with_cli_error,
    exit_with_failure_contract,
    find_recallloom_root,
    latest_active_daily_log,
    latest_active_daily_log_cursor,
    load_workspace_state,
    normalize_wrapper_metadata_json,
    PACKAGE_VERSION,
    parse_iso_date,
    public_project_path,
    read_text,
    resolve_writer_attribution,
    validate_iso_date,
    WrapperMetadataSecurityError,
)


DEFAULT_MAX_INPUT_BYTES = 4 * 1024 * 1024
PREFLIGHT_BINDING_TYPE = "recallloom.preflight_write_binding"
PREFLIGHT_BINDING_VERSION = "0.1"
REVIEW_IMPORTED_BASELINE_CONFIRMATION = "review_imported_baseline_confirmed"
PREFLIGHT_BINDING_ALLOWED_KEYS = {
    "binding_type",
    "binding_version",
    "operation_class",
    "file_key",
    "write_type",
    "target_date",
    "latest_file",
    "latest_entry_id",
    "latest_entry_seq",
    "entry_count",
    "latest_file_digest",
    "contract_type",
    "expected_workspace_revision",
    "expected_revisions",
    "preflight_contract_identity",
    "preflight_contract_hash",
    "provenance_state",
    "write_readiness_label",
    "ux_gate",
    "ux_gate_requires_confirmation",
    "ux_gate_confirmation",
    "ux_gate_reason",
}
PREFLIGHT_BINDING_REQUIRED_KEYS = {
    "binding_type",
    "binding_version",
    "operation_class",
    "file_key",
    "write_type",
    "target_date",
    "latest_file",
    "latest_entry_id",
    "latest_entry_seq",
    "entry_count",
    "latest_file_digest",
    "expected_workspace_revision",
    "preflight_contract_identity",
    "preflight_contract_hash",
}
PREFLIGHT_WRITE_READINESS_LABELS = {
    "structural_only_ready_after_preflight",
    "helper_evidenced_ready_after_preflight",
    "review_imported_baseline_ready_after_preflight",
}


def sha256_text_digest(text: str) -> str:
    return daily_log_append.sha256_text_digest(text)




def positive_int(value: str) -> int:
    try:
        parsed = int(value)
    except ValueError as exc:
        raise argparse.ArgumentTypeError("--max-input-bytes must be an integer.") from exc
    if parsed <= 0:
        raise argparse.ArgumentTypeError("--max-input-bytes must be greater than zero.")
    return parsed


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="Safely append a milestone entry to a RecallLoom daily log."
    )
    parser.add_argument("path", nargs="?", default=".", help="Project path or a descendant path.")
    parser.add_argument("--date", help="Daily log date in YYYY-MM-DD.")
    parser.add_argument(
        "--allow-historical",
        action="store_true",
        help=(
            "Allow appending to a non-latest ISO-dated daily log. "
            "Without this flag, appends to older daily logs are rejected."
        ),
    )
    parser.add_argument("--entry-file", help="Path to prepared entry content.")
    parser.add_argument("--entry-json", help="Prepared entry JSON object as a string.")
    parser.add_argument(
        "--stdin",
        action="store_true",
        help="Read prepared entry content from UTF-8 stdin instead of a file.",
    )
    parser.add_argument(
        "--input-format",
        choices=("auto", "markdown", "json"),
        default="auto",
        help=(
            "Interpret prepared entry input as markdown or JSON. "
            "auto treats --entry-json as JSON and other sources as markdown."
        ),
    )
    parser.add_argument(
        "--max-input-bytes",
        type=positive_int,
        default=DEFAULT_MAX_INPUT_BYTES,
        help="Maximum prepared-entry input size in bytes. Defaults to 4 MiB.",
    )
    parser.add_argument("--expected-workspace-revision", type=int)
    parser.add_argument(
        "--no-auto-detect",
        action="store_true",
        help=(
            "Require explicit --date and --expected-workspace-revision instead of auto-detecting "
            "missing values from the locked workspace state."
        ),
    )
    parser.add_argument("--writer-id")
    parser.add_argument(
        "--wrapper-metadata-json",
        help=(
            "Optional wrapper metadata JSON object for additive public output. "
            "Only public-safe host/surface keys and version-like local_wrapper_version values are accepted."
        ),
    )
    parser.add_argument(
        "--preflight-binding-json",
        help=argparse.SUPPRESS,
    )
    parser.add_argument("--json", action="store_true", help="Print structured JSON output.")
    return parser


def _exit_input_transport_error(
    parser,
    *,
    json_mode: bool,
    error: input_transport.InputTransportError,
) -> None:
    """Project a typed input-transport failure onto the legacy exit contract."""
    exit_with_failure_contract(
        parser,
        json_mode=json_mode,
        exit_code=error.exit_code,
        message=error.message,
        reason=error.reason,
        details=error.details,
    )


def _exit_daily_log_append_planner_error(
    parser,
    *,
    json_mode: bool,
    error: daily_log_append.DailyLogAppendPlannerError,
    legacy_details: dict | None = None,
) -> None:
    """Project a typed pure-planner failure onto the legacy exit contract."""
    def needs_legacy_details(details: dict) -> bool:
        return (
            "hard_block_reasons" in details
            or (
                "missing_section_keys" in details
                and details.get("input_mode") == "stdin"
            )
        )

    if legacy_details:
        if error.details is not None and needs_legacy_details(error.details):
            error.details = {**legacy_details, **error.details}
        if (
            error.payload is not None
            and isinstance(error.payload.get("details"), dict)
            and needs_legacy_details(error.payload["details"])
        ):
            error.payload["details"] = {
                **legacy_details,
                **error.payload["details"],
            }
    if error.payload is not None:
        exit_with_cli_error(
            parser,
            json_mode=json_mode,
            exit_code=error.exit_code,
            message=error.message,
            payload=error.payload,
        )
        raise AssertionError("unreachable")
    exit_with_failure_contract(
        parser,
        json_mode=json_mode,
        exit_code=error.exit_code,
        message=error.message,
        reason=error.reason,
        details=error.details,
    )








def preflight_binding_failure(
    parser,
    *,
    json_mode: bool,
    message: str,
    reason_code: str,
    field_path: str = "$",
    extra: dict | None = None,
) -> None:
    details = {
        "reason_code": reason_code,
        "field_path": field_path,
        "side_effect": "none",
        **(extra or {}),
    }
    exit_with_failure_contract(
        parser,
        json_mode=json_mode,
        exit_code=2,
        message=message,
        reason="invalid_prepared_input",
        details=details,
    )




def normalize_preflight_binding(
    parser,
    *,
    json_mode: bool,
    raw: str | None,
    project_root: Path,
    expected_workspace_revision: int,
) -> dict | None:
    if raw is None:
        return None
    try:
        payload = json.loads(raw)
    except json.JSONDecodeError as exc:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message=f"--preflight-binding-json must be valid JSON: {exc.msg}.",
            reason_code="malformed_preflight_binding_json",
        )
    if not isinstance(payload, dict):
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="--preflight-binding-json must be a JSON object.",
            reason_code="preflight_binding_not_object",
        )
    unknown = sorted(set(payload).difference(PREFLIGHT_BINDING_ALLOWED_KEYS))
    if unknown:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding contains unsupported keys.",
            reason_code="preflight_binding_unknown_key",
            field_path=",".join(unknown),
        )
    missing = sorted(PREFLIGHT_BINDING_REQUIRED_KEYS.difference(payload))
    if missing:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding is missing required fields.",
            reason_code="preflight_binding_missing_required_key",
            field_path=",".join(missing),
        )
    if payload.get("binding_type") != PREFLIGHT_BINDING_TYPE:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding type does not match this helper.",
            reason_code="preflight_binding_type_mismatch",
            field_path="$.binding_type",
        )
    if payload.get("binding_version") != PREFLIGHT_BINDING_VERSION:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding version does not match this helper.",
            reason_code="preflight_binding_version_mismatch",
            field_path="$.binding_version",
        )
    if payload.get("operation_class") != "daily_log_append":
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding operation_class does not match daily-log append.",
            reason_code="preflight_binding_operation_class_invalid",
            field_path="$.operation_class",
        )
    if payload.get("file_key") != "daily_log":
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding file_key does not match daily-log append.",
            reason_code="preflight_binding_file_key_mismatch",
            field_path="$.file_key",
        )
    if payload.get("write_type") != "milestone_evidence":
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding write_type does not match daily-log append.",
            reason_code="preflight_binding_write_type_mismatch",
            field_path="$.write_type",
        )
    target_date = payload.get("target_date")
    if not isinstance(target_date, str) or not target_date.strip():
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding target_date must be an ISO date string.",
            reason_code="preflight_binding_target_date_invalid",
            field_path="$.target_date",
        )
    try:
        parse_iso_date(target_date)
    except ValueError:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding target_date is not a valid ISO date.",
            reason_code="preflight_binding_target_date_invalid",
            field_path="$.target_date",
        )
    for field in ("latest_file", "latest_entry_id"):
        value = payload.get(field)
        if value is not None and (not isinstance(value, str) or not value.strip()):
            preflight_binding_failure(
                parser,
                json_mode=json_mode,
                message=f"Preflight binding {field} must be null or a non-empty string.",
                reason_code=f"preflight_binding_{field}_invalid",
                field_path=f"$.{field}",
            )
    for field in ("latest_entry_seq", "entry_count"):
        value = payload.get(field)
        if value is not None and (not isinstance(value, int) or isinstance(value, bool) or value < 0):
            preflight_binding_failure(
                parser,
                json_mode=json_mode,
                message=f"Preflight binding {field} must be null or a non-negative integer.",
                reason_code=f"preflight_binding_{field}_invalid",
                field_path=f"$.{field}",
            )
    latest_file_digest = payload.get("latest_file_digest")
    if latest_file_digest is not None and (
        not isinstance(latest_file_digest, str)
        or not latest_file_digest.startswith("sha256:")
    ):
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding latest_file_digest must be null or a sha256 digest string.",
            reason_code="preflight_binding_latest_file_digest_invalid",
            field_path="$.latest_file_digest",
        )
    if payload.get("expected_workspace_revision") != expected_workspace_revision:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding expected_workspace_revision does not match this append.",
            reason_code="preflight_binding_workspace_revision_mismatch",
            field_path="$.expected_workspace_revision",
        )
    expected_preflight_identity = provenance_contract_identity()
    if payload.get("preflight_contract_identity") != expected_preflight_identity:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding contract identity does not match the active provenance contract.",
            reason_code="preflight_binding_contract_identity_mismatch",
            field_path="$.preflight_contract_identity",
            extra={"expected_preflight_contract_identity": expected_preflight_identity},
        )
    expected_binding_hash = preflight_write_binding_hash(payload)
    if payload.get("preflight_contract_hash") != expected_binding_hash:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding hash does not match the canonical binding payload.",
            reason_code="preflight_binding_hash_mismatch",
            field_path="$.preflight_contract_hash",
            extra={"expected_preflight_contract_hash": expected_binding_hash},
        )
    try:
        assert_public_safe_json(payload, project_root=str(project_root))
    except ValueError as exc:
        details = getattr(exc, "details", {})
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding is not public-safe.",
            reason_code=str(details.get("reason_code") or "preflight_binding_privacy_violation"),
            field_path=str(details.get("field_path") or "$"),
        )
    return payload


def preflight_cursor_is_no_log(cursor: dict[str, object]) -> bool:
    return (
        cursor.get("latest_file") is None
        and cursor.get("latest_entry_id") is None
        and cursor.get("latest_entry_seq") in {0, None}
        and cursor.get("entry_count") in {0, None}
    )


def enforce_preflight_daily_log_cursor(
    parser,
    *,
    json_mode: bool,
    workspace,
    state: dict,
    preflight_binding: dict | None,
    target_date: date,
    latest_existing: Path | None,
) -> None:
    if preflight_binding is None:
        return
    target_date_iso = target_date.isoformat()
    if preflight_binding.get("target_date") != target_date_iso:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding target_date does not match this append.",
            reason_code="preflight_binding_target_date_mismatch",
            field_path="$.target_date",
            extra={
                "binding_target_date": preflight_binding.get("target_date"),
                "actual_target_date": target_date_iso,
            },
        )

    daily_state = state.get("daily_logs")
    if not isinstance(daily_state, dict):
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="state.json daily_logs cursor is unavailable for append binding verification.",
            reason_code="preflight_binding_daily_log_cursor_unavailable",
            field_path="$.daily_logs",
        )

    latest_file = (
        latest_existing.relative_to(workspace.storage_root).as_posix()
        if latest_existing is not None
        else None
    )
    state_cursor = {
        "latest_file": daily_state.get("latest_file"),
        "latest_entry_id": daily_state.get("latest_entry_id"),
        "latest_entry_seq": daily_state.get("latest_entry_seq"),
        "entry_count": daily_state.get("entry_count"),
    }
    actual_cursor = dict(state_cursor)
    actual_latest_digest = None
    if latest_existing is not None:
        try:
            latest_text = read_text(latest_existing)
        except (OSError, UnicodeDecodeError) as exc:
            preflight_binding_failure(
                parser,
                json_mode=json_mode,
                message=f"Could not read latest daily log for append binding verification: {exc}",
                reason_code="preflight_binding_daily_log_cursor_unreadable",
                field_path="$.latest_file",
            )
        actual_latest_digest = sha256_text_digest(latest_text)
        try:
            actual_cursor = daily_log_cursor_state_fields(
                latest_active_daily_log_cursor(workspace.storage_root).as_state_fields()
            )
        except DailyLogCursorError as exc:
            preflight_binding_failure(
                parser,
                json_mode=json_mode,
                message=str(exc),
                reason_code=exc.reason_code,
                field_path="$.daily_logs",
                extra={"actual_latest_file": latest_file},
            )
    elif daily_state.get("latest_file") is None:
        actual_cursor = {
            "latest_file": None,
            "latest_entry_id": None,
            "latest_entry_seq": 0,
            "entry_count": 0,
        }
        state_cursor = dict(actual_cursor)

    binding_cursor = {
        "latest_file": preflight_binding.get("latest_file"),
        "latest_entry_id": preflight_binding.get("latest_entry_id"),
        "latest_entry_seq": preflight_binding.get("latest_entry_seq"),
        "entry_count": preflight_binding.get("entry_count"),
    }
    if preflight_cursor_is_no_log(binding_cursor) and daily_log_cursor_is_legacy_empty(actual_cursor):
        binding_cursor = dict(actual_cursor)
    binding_latest_digest = preflight_binding.get("latest_file_digest")

    if not daily_log_cursors_equivalent(
        binding_cursor,
        state_cursor,
        actual_cursor=actual_cursor,
    ):
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding daily-log cursor does not match current state.",
            reason_code="preflight_binding_daily_log_cursor_mismatch",
            field_path="$.daily_logs",
            extra={
                "binding_cursor": binding_cursor,
                "state_cursor": state_cursor,
            },
        )
    if not daily_log_cursors_equivalent(
        state_cursor,
        actual_cursor,
        actual_cursor=actual_cursor,
    ):
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Current latest daily-log file does not match the state cursor.",
            reason_code="preflight_binding_daily_log_file_cursor_mismatch",
            field_path="$.daily_logs",
            extra={
                "state_cursor": state_cursor,
                "actual_cursor": actual_cursor,
            },
        )
    if binding_latest_digest != actual_latest_digest:
        preflight_binding_failure(
            parser,
            json_mode=json_mode,
            message="Preflight binding latest daily-log digest does not match the current file.",
            reason_code="preflight_binding_daily_log_digest_mismatch",
            field_path="$.latest_file_digest",
            extra={
                "binding_latest_file_digest": binding_latest_digest,
                "actual_latest_file_digest": actual_latest_digest,
            },
        )


def build_append_failure_details(
    *,
    project_root: Path,
    target_path: Path,
    target_date: str,
    current_workspace_revision: int,
    entry_path: Path | None,
    input_mode: str,
    extra: dict | None = None,
) -> dict:
    details: dict[str, object] = {
        "project_root": str(project_root),
        "target_path": str(target_path),
        "target_date": target_date,
        "current_workspace_revision": current_workspace_revision,
        "input_mode": input_mode,
    }
    if entry_path is not None:
        details["entry_path"] = str(entry_path)
    if extra:
        details.update(extra)
    return details


def legacy_append_input_mode(*, acquired_mode: str, input_format: str) -> str:
    """Map the transport vocabulary onto the frozen append CLI vocabulary."""
    if acquired_mode == "entry-json":
        return "json-string"
    if input_format == "json":
        return "json-file" if acquired_mode == "file" else "json-stdin"
    return acquired_mode


def resolve_target_date(
    *,
    explicit_date: str | None,
    latest_existing: Path | None,
    logical_workday: date,
) -> tuple[date, date | None, str]:
    return daily_log_append.resolve_target_date(
        explicit_date=explicit_date,
        latest_existing=latest_existing,
        logical_workday=logical_workday,
    )


def exit_with_append_date_guard(
    parser,
    *,
    json_mode: bool,
    workspace_language: str,
    exit_code: int,
    reason: str,
    message: str,
    details: dict,
) -> None:
    exit_with_cli_error(
        parser,
        json_mode=json_mode,
        exit_code=exit_code,
        message=message,
        payload=failure_payload(
            reason,
            language=workspace_language,
            error=message,
            details=details,
        ),
    )


def enforce_logical_workday_append_guards(
    parser,
    *,
    json_mode: bool,
    workspace_language: str,
    target_path: Path,
    target_date: date,
    latest_existing: Path | None,
    logical_workday: date | None = None,
    recovery_details: dict | None = None,
) -> date | None:
    if logical_workday is None:
        logical_workday = logical_workday_for(
            datetime.now().astimezone(),
            DEFAULT_LOGICAL_WORKDAY_ROLLOVER_HOUR,
        )
    logical_workday_iso = logical_workday.isoformat()
    latest_existing_date = parse_iso_date(latest_existing.stem) if latest_existing is not None else None
    latest_existing_text = str(latest_existing) if latest_existing is not None else None
    base_details = dict(recovery_details or {})
    base_details.update(
        {
            "target_path": str(target_path),
            "target_date": target_date.isoformat(),
            "logical_workday": logical_workday_iso,
            "latest_active_daily_log": latest_existing_text,
        }
    )

    if target_date > logical_workday:
        message = (
            f"Refusing to append to future-dated daily log {target_path}. "
            f"The current logical workday is {logical_workday_iso}. "
            "--allow-historical only applies to intentional historical backfills and cannot override "
            "future-dated append guards."
        )
        exit_with_append_date_guard(
            parser,
            json_mode=json_mode,
            workspace_language=workspace_language,
            exit_code=2,
            reason="project_time_policy_review_required",
            message=message,
            details=base_details,
        )

    if latest_existing_date is not None and latest_existing_date > logical_workday:
        details = dict(base_details)
        details["latest_active_day"] = latest_existing_date.isoformat()
        message = (
            "Refusing to append because the latest active ISO-dated daily log "
            f"{latest_existing} is ahead of the current logical workday {logical_workday_iso}. "
            "Review the active date before appending to any daily log. "
            "--allow-historical only applies to intentional historical backfills and cannot override "
            "future-dated append guards."
        )
        exit_with_append_date_guard(
            parser,
            json_mode=json_mode,
            workspace_language=workspace_language,
            exit_code=2,
            reason="project_time_policy_review_required",
            message=message,
            details=details,
        )

    return latest_existing_date


def main() -> None:
    """CLI/input/legacy-output adapter; transaction owns every mutation stage."""
    parser = build_parser()
    args = parser.parse_args()
    exit_with_failure_contract(
        parser, json_mode=args.json, exit_code=3,
        message=("Direct mutation helper invocation is not authorized. "
                 "Use the RecallLoom dispatcher for this transaction."),
        reason="invalid_transaction_authority",
        details={"side_effect": "none"},
    )
    raise AssertionError("unreachable")


def run_from_dispatcher(argv: list[str], *, authority) -> None:
    """Trusted in-process adapter entry; the dispatcher owns authority."""
    parser = build_parser()
    args = parser.parse_args(argv)
    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)))
    support = enforce_package_support_gate(parser, json_mode=args.json)
    try:
        wrapper_metadata = normalize_wrapper_metadata_json(args.wrapper_metadata_json)
        if args.date is not None and not validate_iso_date(args.date):
            exit_with_failure_contract(parser, json_mode=args.json, exit_code=2,
                                       message=f"Invalid --date value: {args.date}", reason="invalid_date", details={"date": args.date})
        attribution = resolve_writer_attribution(explicit_writer_id=args.writer_id,
                                                 invocation_surface="append_daily_log_entry.py",
                                                 wrapper_metadata=wrapper_metadata)
        workspace = find_recallloom_root(args.path)
    except WrapperMetadataSecurityError as exc:
        exit_with_failure_contract(parser, json_mode=args.json, exit_code=4, message=str(exc),
                                   reason="privacy_security_failure", details=exc.details)
    except ConfigContractError as exc:
        exit_with_failure_contract(parser, json_mode=args.json, exit_code=2, message=str(exc),
                                   reason="invalid_tool_name", details={"writer_id_source": "explicit_cli"})
    except StorageResolutionError 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"))
    if workspace is None:
        exit_with_failure_contract(parser, json_mode=args.json, exit_code=1,
                                   message="No RecallLoom project root found.", reason="no_project_root")
    startup_residue_report = exit_if_startup_scratch_residue_for_sources(
        parser, json_mode=args.json, project_root=workspace.project_root,
        storage_root=workspace.storage_root, source_paths=[args.entry_file])
    state_path = workspace.storage_root / FILE_KEYS["state"]
    state = load_workspace_state(state_path)
    latest_existing = latest_active_daily_log(workspace.storage_root / DAILY_LOGS_DIRNAME)
    logical_workday = logical_workday_for(datetime.now().astimezone(), DEFAULT_LOGICAL_WORKDAY_ROLLOVER_HOUR)
    cues_path = workspace.storage_root / FILE_KEYS["update_protocol"]
    cues = detect_update_protocol_time_policy_cues(read_text(cues_path)) if cues_path.is_file() else []
    if args.date is None and cues:
        exit_with_append_date_guard(parser, json_mode=args.json, workspace_language=workspace.workspace_language,
            exit_code=2, reason="project_time_policy_review_required",
            message="Project-local time-policy cues were detected in update_protocol.md. Append requires an explicit --date before writing when date auto-detect would otherwise apply.",
            details={"logical_workday": logical_workday.isoformat(), "project_time_policy_cues": cues})
    target_date, latest_existing_date, date_resolution_source = resolve_target_date(
        explicit_date=args.date, latest_existing=latest_existing, logical_workday=logical_workday)
    target_path = workspace.storage_root / DAILY_LOGS_DIRNAME / f"{target_date.isoformat()}.md"
    expected_workspace_revision = state["workspace_revision"] if args.expected_workspace_revision is None else args.expected_workspace_revision
    details = build_append_failure_details(project_root=workspace.project_root, target_path=target_path,
        target_date=target_date.isoformat(), current_workspace_revision=state["workspace_revision"],
        entry_path=Path(args.entry_file) if args.entry_file else None, input_mode=None, extra={})
    latest_existing_date = enforce_logical_workday_append_guards(parser, json_mode=args.json,
        workspace_language=workspace.workspace_language, target_path=target_path, target_date=target_date,
        latest_existing=latest_existing, logical_workday=logical_workday, recovery_details=details)
    historical = latest_existing_date is not None and target_date < latest_existing_date
    if historical and not args.allow_historical:
        historical_input_mode = (
            "json-string" if args.entry_json is not None
            else "file" if args.entry_file is not None
            else "stdin"
        )
        historical_details = build_append_failure_details(
            project_root=workspace.project_root, target_path=target_path,
            target_date=target_date.isoformat(),
            current_workspace_revision=state["workspace_revision"],
            entry_path=Path(args.entry_file) if args.entry_file else None,
            input_mode=historical_input_mode, extra={
                "auto_detected_date": args.date is None,
                "auto_detected_workspace_revision": args.expected_workspace_revision is None,
                "date_resolution_source": date_resolution_source,
                "workspace_revision_source": "state_current" if args.expected_workspace_revision is None else "explicit",
                "logical_workday": logical_workday.isoformat(),
                "latest_active_daily_log": str(latest_existing),
                "latest_active_day": latest_existing_date.isoformat(),
            })
        message = (
            f"Refusing to append to non-latest daily log {target_path}. "
            f"The latest active ISO-dated daily log is {latest_existing}. "
            "Re-run with --allow-historical only when you intentionally need a historical append."
        )
        exit_with_cli_error(parser, json_mode=args.json, exit_code=2,
            message=message,
            payload=failure_payload("historical_append_requires_confirmation", language=workspace.workspace_language, error=message, details=historical_details))
    binding = normalize_preflight_binding(parser, json_mode=args.json, raw=args.preflight_binding_json,
        project_root=workspace.project_root, expected_workspace_revision=expected_workspace_revision)
    if binding is not None and historical:
        exit_with_cli_error(parser, json_mode=args.json, exit_code=3,
            message="Refusing receipt-backed append to a historical daily log. v0.4.2 provenance receipts only bind the current latest daily-log cursor.",
            payload=failure_payload("historical_append_not_receipt_backed", language=workspace.workspace_language, error="Historical append is not receipt backed.", details=details))
    enforce_preflight_daily_log_cursor(parser, json_mode=args.json, workspace=workspace, state=state,
        preflight_binding=binding, target_date=target_date, latest_existing=latest_existing)
    try:
        acquired = recording_transaction.acquire_preview_input(operation=OPERATION_DAILY_LOG_APPEND,
            entry_json=args.entry_json, entry_file=args.entry_file, use_stdin=args.stdin,
            max_input_bytes=args.max_input_bytes, project_root=workspace.project_root, storage_root=workspace.storage_root)
    except input_transport.InputTransportError as exc:
        _exit_input_transport_error(parser, json_mode=args.json, error=exc)
        raise AssertionError("unreachable")
    output_input_mode = legacy_append_input_mode(
        acquired_mode=acquired.input_mode,
        input_format=args.input_format,
    )
    if args.entry_json is not None:
        try:
            daily_log_append.prepare_entry_text(
                acquired, input_format=args.input_format, entry_path=None,
                project_root=workspace.project_root,
            )
        except daily_log_append.DailyLogAppendPlannerError as exc:
            _exit_daily_log_append_planner_error(parser, json_mode=args.json, error=exc)
    planner_failure_details = build_append_failure_details(
        project_root=workspace.project_root,
        target_path=target_path,
        target_date=target_date.isoformat(),
        current_workspace_revision=state["workspace_revision"],
        entry_path=Path(args.entry_file) if args.entry_file else None,
        input_mode=output_input_mode,
        extra={
            "auto_detected_date": args.date is None,
            "auto_detected_workspace_revision": args.expected_workspace_revision is None,
            "date_resolution_source": date_resolution_source,
            "workspace_revision_source": (
                "state_current"
                if args.expected_workspace_revision is None
                else "explicit"
            ),
            "logical_workday": logical_workday.isoformat(),
            "latest_active_daily_log": (
                str(latest_existing) if latest_existing else None
            ),
            "latest_active_day": (
                latest_existing_date.isoformat() if latest_existing_date else None
            ),
        },
    )
    if args.no_auto_detect and (args.date is None or args.expected_workspace_revision is None):
        missing = [name for name, value in (("date", args.date), ("expected_workspace_revision", args.expected_workspace_revision)) if value is None]
        exit_with_failure_contract(parser, json_mode=args.json, exit_code=2,
            message="--no-auto-detect requires explicit --date and --expected-workspace-revision. Missing: " + ", ".join(missing) + ".",
            reason="invalid_prepared_input", details={
                "project_root": str(workspace.project_root),
                "input_mode": output_input_mode,
                "missing_fields": missing, "no_auto_detect": True,
            })
    if state["workspace_revision"] != expected_workspace_revision:
        message = (
            f"Workspace revision changed from {expected_workspace_revision} to "
            f"{state['workspace_revision']}. Rerun preflight before appending."
        )
        exit_with_cli_error(parser, json_mode=args.json, exit_code=3, message=message,
            payload=failure_payload("stale_write_context", language=workspace.workspace_language,
                error=message, details={
                    "expected_workspace_revision": expected_workspace_revision,
                    **planner_failure_details,
                }))
    cursor = daily_log_cursor_state_fields(state.get("daily_logs", {}))
    cursor["target_path"] = str(target_path)
    cursor["target_is_latest_after_write"] = not historical
    expected_file_revision = 0
    if target_path.is_file():
        expected_file_revision = daily_log_cursor_from_text(read_text(target_path), path=target_path, latest_file=target_path.relative_to(workspace.storage_root).as_posix()).entry_count
    request = recording_transaction.TransactionRequest(context=OperationContext(command=COMMAND_APPEND, operation=OPERATION_DAILY_LOG_APPEND, write_type="milestone_evidence", input_mode=acquired.input_mode, stage=STAGE_PREFLIGHT),
        mode=recording_transaction.MODE_APPLY, workspace_root=workspace.project_root, storage_root=workspace.storage_root,
        acquired_input=acquired, file_key="daily_log", write_type="milestone_evidence",
        expected_file_revision=expected_file_revision, expected_workspace_revision=expected_workspace_revision,
        expected_cursor=cursor, expected_input_digest=None, preview_binding=None, confirmation=None, writer_attribution=attribution)
    outcome = recording_transaction.run_transaction(request, support=support, preflight_binding=binding, authority=authority,
        package_version=PACKAGE_VERSION, input_format=args.input_format, source_file=args.entry_file)
    if isinstance(outcome, recording_transaction.TransactionFailure):
        cause = outcome.cause
        if isinstance(cause, daily_log_append.DailyLogAppendPlannerError):
            _exit_daily_log_append_planner_error(
                parser,
                json_mode=args.json,
                error=cause,
                legacy_details=planner_failure_details,
            )
        if isinstance(cause, recording_transaction.TransactionStageError):
            exit_with_failure_contract(parser, json_mode=args.json, exit_code=cause.exit_code, message=cause.message, reason=cause.reason, details=cause.details, findings=cause.findings, extra=cause.extra)
        raise AssertionError(f"untyped transaction failure: {cause!r}")
    result, receipt_finalization = outcome
    payload = {"ok": True, "input_mode": output_input_mode, "target_path": str(target_path),
        "entry_seq": result.revisions["new_file_revision"], "new_workspace_revision": result.revisions["new_workspace_revision"],
        "allow_historical": args.allow_historical, "state_cursor_updated": not historical, **attribution.public_fields(),
        "auto_detect": {"date_used": args.date is None, "workspace_revision_used": args.expected_workspace_revision is None,
            "logical_workday": logical_workday.isoformat(), "latest_active_daily_log": str(latest_existing) if latest_existing else None,
            "latest_active_day": latest_existing_date.isoformat() if latest_existing_date else None, "resolved_date": target_date.isoformat(),
            "resolved_workspace_revision": expected_workspace_revision, "date_resolution_source": date_resolution_source,
            "workspace_revision_source": "state_current" if args.expected_workspace_revision is None else "explicit",
            "workspace_revision_guard_mode": "lock_snapshot_current" if args.expected_workspace_revision is None else "explicit_mismatch_check"}}
    if wrapper_metadata is not None: payload["wrapper_metadata"] = wrapper_metadata
    if receipt_finalization is not None:
        receipt = receipt_finalization["receipt"]
        payload.update({"provenance_state": "helper_evidenced", "provenance_result": {"state_label": "helper_evidenced", "receipt_backed": True, "receipt_finalization_status": "finalized", "receipt_store_available": True, "receipt_digest": receipt_finalization["receipt_digest"], "store_binding": receipt_finalization["store_binding"], "redaction_policy_version": receipt.get("redaction_policy_version")}, "public_receipt_claim": public_receipt_claim(receipt, project_root=str(workspace.project_root))})
    if args.json:
        if startup_residue_report is not None: payload["startup_residue_report"] = startup_residue_report
        print(json.dumps(publicize_json_value(payload, project_root=workspace.project_root), ensure_ascii=False, indent=2))
    else:
        print(f"Appended daily log entry to {public_project_path(target_path, project_root=workspace.project_root) or 'daily log'}")


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