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

references/file-contracts.md

View on GitHub
# File Contracts

## Contents

- `STORAGE_ROOT/config.json`
- `STORAGE_ROOT/state.json`
- `STORAGE_ROOT/context_brief.md`
- `STORAGE_ROOT/rolling_summary.md`
- `STORAGE_ROOT/daily_logs/YYYY-MM-DD.md`
- `STORAGE_ROOT/update_protocol.md`
- `STORAGE_ROOT/companion/`
- Helper JSON surfaces

## `STORAGE_ROOT/config.json`

Role:

- machine-readable workspace settings

Expected fields:

- `protocol_version`
- `storage_mode`
- `workspace_language`
- `created_by`
- `created_at`

## `STORAGE_ROOT/state.json`

Role:

- machine-readable sidecar state for concurrency-aware helper behavior

Expected fields:

- `workspace_revision`
- `update_protocol_revision`
- `git_exclude_mode`
- `bridged_entries`
- `files`
- `daily_logs`

This file is maintained by helper scripts and supports:

- revision-aware checks
- bridge state
- git exclude state
- daily log state

Protocol `1.0` scope note:

- helper-only routing fields such as `sidecar_trust_state`
- `provenance_state`
- `write_readiness`
- `expected_revisions`
- `preflight_contract_identity`
- `continuity_drift_risk_level`
- `allowed_operation_level`

are helper/dispatcher JSON routing surfaces, not persisted write authority.
`state.json.provenance` may store local provenance markers such as `structurally_valid`, `review_imported_baseline`, or `helper_evidenced` after a receipt-finalized helper write.
Legacy sidecars without this metadata remain readable, but mutating helper writes must first pass review / repair import.
`helper_evidenced` is reserved for a successfully finalized helper receipt; structural validation or review import alone must remain `structurally_valid`, `review_imported_baseline`, or another non-receipt-backed provenance state.

Package support fields such as `package_support_state`, advisory source, and daily support-cache status are also not persisted into `state.json`.
They belong to the installed package runtime and user-level cache, not to the project sidecar.

Expected `files` entries:

- `files.context_brief`
- `files.rolling_summary`
- `files.update_protocol`

Each file entry must contain:

- `file_revision`
- `updated_at`
- `writer_id`
- `base_workspace_revision`

Expected `daily_logs` fields:

- `latest_file`
- `latest_entry_id`
- `latest_entry_seq`
- `entry_count`
- `updated_at` (optional helper-maintained timestamp)

Expected `bridged_entries` value shape:

- each key is a supported root entry file path
- each value may include:
  - `update_protocol_revision_seen`
  - `latest_daily_log_seen`
  - `updated_at`

`daily_logs` state semantics:

- these fields describe the latest **active** ISO-dated daily log under `STORAGE_ROOT/daily_logs/`
- archived files under `STORAGE_ROOT/daily_logs/archive/` are excluded from this cursor
- for the current package line on protocol `1.0`, `latest_entry_seq` is the file-local sequence number of the latest entry marker in that latest active daily log
- `entry_count` remains the field name for protocol `1.0`; it means the number of entry markers in the latest active daily log file, not a cross-file global cumulative count
- helper-generated canonical `latest_entry_id` mirrors the latest entry marker id, where the canonical marker id is `entry-{entry_seq}` for that file-local sequence
- archiving older logs without changing the latest active daily-log cursor should not by itself advance `workspace_revision`
- when no active daily log exists, helpers must write:
  - `latest_file = null`
  - `latest_entry_id = null`
  - `latest_entry_seq = 0`
  - `entry_count = 0`
- when the latest active daily log is an empty scaffold, helpers must keep `latest_file = daily_logs/YYYY-MM-DD.md` while writing:
  - `latest_entry_id = null`
  - `latest_entry_seq = null`
  - `entry_count = 0`

Allowed `storage_mode` values:

- `hidden`
- `visible`

Meaning:

- `hidden` means the storage root is `PROJECT_ROOT/.recallloom/`
- `visible` means the storage root is `PROJECT_ROOT/recallloom/`

Contract rule:

- exactly one valid storage root may exist for a project at a time
- if both hidden and visible sidecars exist with `config.json`, the workspace is in an invalid conflict state
- `storage_mode` must match the physical storage root that contains this config file
- the storage root is reserved for RecallLoom-managed assets only
- helper-visible managed assets should be resolved from the package-level managed asset registry
  `recallloom/managed-assets.json`

This file should remain stable unless the workspace configuration itself changes.

Invalid states include:

- malformed JSON
- missing required fields
- unsupported `protocol_version`
- unsupported `storage_mode`
- unsupported `workspace_language`

Language consistency rule:

- all managed file markers in the storage root must use the same language value as `workspace_language`

Current supported `workspace_language` values for protocol `1.0`:

- `en`
- `zh-CN`

Managed asset registry note:

- protocol `1.0` core semantics remain defined by this document
- the current package line additionally ships `recallloom/managed-assets.json`
  as the single declaration source for:
  - required managed files
  - optional managed files
  - required managed directories
  - allowed managed directories
  - allowed dynamic file patterns
  - optional managed namespaces
- helpers should consume that registry instead of maintaining repeated hard-coded path allowlists

<!-- RecallLoom metadata sync start: file-contract-registry-summary -->
Generated from `references/contract-registry.json`.

### `config`

- path: `config.json`
- required sections:
  - none
- optional sections:
  - none
- render order:
  - none

### `state`

- path: `state.json`
- required sections:
  - none
- optional sections:
  - none
- render order:
  - none

### `context_brief`

- path: `context_brief.md`
- required sections:
  - `mission`
  - `current_phase`
  - `source_of_truth`
  - `core_workflow`
  - `boundaries`
- optional sections:
  - `audience_stakeholders`
  - `scope`
- render order:
  - `mission`
  - `audience_stakeholders`
  - `current_phase`
  - `scope`
  - `source_of_truth`
  - `core_workflow`
  - `boundaries`

### `rolling_summary`

- path: `rolling_summary.md`
- required sections:
  - `current_state`
  - `active_judgments`
  - `risks_open_questions`
  - `next_step`
  - `recent_pivots`
- optional sections:
  - none
- render order:
  - `current_state`
  - `active_judgments`
  - `risks_open_questions`
  - `next_step`
  - `recent_pivots`

### `daily_log`

- path: `daily_logs/{date}.md`
- required sections:
  - `work_completed`
  - `confirmed_facts`
  - `key_decisions`
  - `risks_blockers`
  - `recommended_next_step`
- optional sections:
  - none
- render order:
  - `work_completed`
  - `confirmed_facts`
  - `key_decisions`
  - `risks_blockers`
  - `recommended_next_step`

### `update_protocol`

- path: `update_protocol.md`
- required sections:
  - `project_specific_overrides`
- optional sections:
  - none
- render order:
  - `project_specific_overrides`
<!-- RecallLoom metadata sync end: file-contract-registry-summary -->

Version consistency rule:

- `protocol_version` must use a supported RecallLoom protocol version
- protocol `1.0` uses dotted string form such as `1.0`

## Helper JSON Surfaces

Role:

- structured JSON guidance emitted by helpers and the dispatcher
- not persisted into `STORAGE_ROOT`
- versioned independently from the sidecar file protocol

Current contract distinction:

- sidecar `protocol_version` remains `1.0`
- helper output `schema_version` may be `1.1`

Compatibility rules:

- `schema_version: "1.1"` is a helper output contract, not a sidecar protocol
  upgrade
- new helper fields are additive and optional unless this section explicitly
  marks them required for a specific surface
- existing consumers may ignore unknown helper-output fields
- existing required JSON fields on documented stable surfaces must not be
  removed or renamed within the current helper schema `1.x` line

Field semantics for helper schema `1.1`:

- `schema_version`
  - required when a payload opts into helper schema `1.1`
  - dotted string naming the helper output contract line
  - current value is `1.1`
- `next_actions`
  - ordered array of stable machine-readable action tokens
  - expresses the preferred next moves from most immediate to less immediate
  - tokens are contract identifiers, not localized display strings
- `suggestion`
  - short localized human-readable guidance string
  - summarizes the preferred recovery or follow-up action
  - complements `next_actions`; it does not rename those tokens
- `recovery_command`
  - single preferred actionable recovery instruction
  - use a literal command string when a deterministic rerun path exists
  - otherwise use a concise imperative instruction instead of fabricating a
    fake shell command
- `single_next_command`
  - additive failure-payload field with one dispatcher-oriented command to try
    next
  - placeholders such as `<project-path>` are intentionally public-safe and
    should be replaced by the operator or wrapper
- `safe_to_retry`
  - additive boolean on shared failure payloads
  - true only when the helper reports no side effect and no trust impact
- `side_effect`
  - additive failure-payload field describing whether the failed helper changed
    anything; public values include `none`, `partial`, `write_attempted`, and
    `unknown`
- `trust_effect`
  - shared failure-payload field describing the trust impact of the failure
  - consumers should treat anything other than `none` as review-required before
    retrying a mutating operation
- `read_plan`
  - optional structured read recommendation for follow-up continuity loading
  - additive in schema `1.1`; consumers that do not understand it may ignore
    it entirely
- `estimated_tokens`
  - optional integer estimate for the helper-defined read budget
  - when `read_plan` is present, this top-level value is the default
    `standard` tier budget and must equal
    `read_plan.standard.estimated_tokens`
- `progressive_read_plan`
  - optional structured read plan for bounded `resume --fast` and
    `resume --full` surfaces
  - distinct from the E2 tiered `read_plan` contract used by ambient
    `status --json` and bare `resume --json`
  - consumers that do not understand it may ignore it entirely

`read_plan` contract for E2:

- `read_plan` is an object with at least these named tiers:
  - `minimal`
  - `standard`
  - `comprehensive`
- future helper schemas may add more tiers; existing consumers may ignore
  unknown tier keys

Each required tier must contain:

- `files`
  - ordered list of project-root-relative paths to read next
  - use the actual storage-root prefix under the project root, such as
    `.recallloom/...` or `recallloom/...`
  - do not emit absolute paths, bare storage-root-relative fragments, or
    ambiguous aliases
- `reason`
  - short explanation of why the listed files are sufficient for that tier
  - this is the normative place to say `review-before-write` when the plan is
    only safe after additional human review
- `estimated_tokens`
  - integer estimate for reading the files listed in that tier
  - this is a plan budget hint, not an exact tokenizer promise

Tier intent:

- `minimal`
  - smallest bounded continuity set for orientation
  - centers on current-state files instead of deep history
  - should not expand into extra evidence unless safety or freshness requires
    it
- `standard`
  - default balanced tier for most follow-up work
  - should extend `minimal` with framing and project-local constraints when
    available
- `comprehensive`
  - highest-confidence tier for stale, conflicting, or evidence-heavy cases
  - may add the latest active daily log and other directly relevant managed
    evidence

`repair-daily-log-cursor` success payloads:

- preview mode returns `mode: "preview"`, `dry_run: true`, `applied: false`,
  `repair_eligible`, `current_cursor`, `expected_cursor`, and `next_action`
- apply mode returns `mode: "apply"` and uses the same cursor fields; when a
  repair is applied it also returns a public `provenance_decision` summary
- apply mode repairs only the `state.json.daily_logs` cursor fields and
  repair-decision provenance metadata; it does not rewrite daily-log files or
  create helper receipts

Review-before-write rule:

- when `update_protocol.md` exists or governs the action, every tier reason
  must explicitly include `review-before-write`, and every tier file list must
  include the project-root-relative `update_protocol.md` path
- when `rolling_summary.md` is stale, every tier reason must explicitly
  include `review-before-write`
- in stale-summary cases, the tier file list must include
  the project-root-relative `state.json` and `rolling_summary.md` paths under
  the resolved storage root, plus any identified newer managed artifact path
  when that path is known
- consumers must treat these markers as read gates, not as automatic write
  approval

Budget relationship to `query_continuity.py`:

- `read_plan.*.estimated_tokens` and the top-level helper `estimated_tokens`
  describe the cost of executing the suggested read plan
- they do not replace, rename, or retroactively reinterpret
  `query_continuity.py` fields `token_estimate` or `budget_hint`
- `query_continuity.py.token_estimate` continues to estimate the size of the
  returned recall text
- `query_continuity.py.budget_hint` remains its coarse answer-size bucket

`progressive_read_plan` contract for F1:

- only emit this field for explicit bounded progressive resume modes such as
  `resume --fast --json` and `resume --full --json`
- do not emit the E2 tiered `read_plan` on those explicit progressive modes
- required fields:
  - `mode`: `fast` or `full`
  - `files`: ordered project-root-relative paths the mode used for its bounded
    read surface
  - `reason`: short explanation of why that bounded surface is appropriate
  - `estimated_tokens`: integer estimate for reading the listed files
  - `bounded`: boolean value that must be `true`

Mode intent:

- `fast`
  - use when the agent only needs current-state orientation and the latest
    summary is enough to decide the next safe move
  - read `state.json` and `rolling_summary.md`
  - do not read daily logs by default
- `full`
  - use when stable project framing, source-of-truth routing, or
    `update_protocol.md` guidance is needed before choosing an action
  - extend the bounded read surface with `context_brief.md` and
    `update_protocol.md`
  - keep daily-log evidence on demand through `query_continuity.py`

## `STORAGE_ROOT/context_brief.md`

Role:

- stable onboarding and framing file

Required file marker:

- `recallloom:file=context_brief`

Required metadata marker:

- a valid file-state marker must appear in the leading metadata block
- the recommended protocol `1.0` writer position is line 2
- helper-generated files currently place it on line 2
- current readers accept it within the first four lines as a compatibility tolerance, not as a relaxed writer contract

Language rule:

- marker `lang` must match `config.json.workspace_language`

Version rule:

- marker `version` must use a supported RecallLoom protocol version
- when `config.json.protocol_version` is supported, marker `version` should match it

Required file-state marker shape:

```text
<!-- file-state: revision=<n> | updated-at=<timestamp> | writer-id=<writer> | base-workspace-revision=<n> -->
```

Operational rule:

- helper commits should refuse stale writes when the prepared file revision or workspace revision no longer matches

Recommended sections:

1. Mission
2. Audience / Stakeholders
3. Current Phase
4. Scope
5. Source of Truth
6. Core Workflow
7. Boundaries

Required section keys:

- `mission`
- `current_phase`
- `source_of_truth`
- `core_workflow`
- `boundaries`

Optional but recommended section keys:

- `audience_stakeholders`
- `scope`

Do not use it for:

- running task logs
- fast-changing details
- detailed milestone history

## `STORAGE_ROOT/companion/`

Role:

- optional managed namespace for companion-layer assets

Current package-line purpose:

- hold recovery proposals and related review records under the sidecar without creating a second root

Contract rule:

- this namespace is optional
- its absence must not make a healthy `1.0` workspace invalid
- files inside it must still be RecallLoom-managed assets, not arbitrary user files
- allowed child directories and dynamic file patterns are declared by
  `recallloom/managed-assets.json`

Current recognized subtree in this package line:

- `STORAGE_ROOT/companion/recovery/`

This subtree is for:

- recovery proposals
- review records
- archived recovery artifacts

It is not for:

- raw transcript dumps kept indefinitely
- unrelated project notes
- replacing `rolling_summary.md`, `daily_logs/`, or `context_brief.md`

## `STORAGE_ROOT/rolling_summary.md`

Role:

- overwrite-style current-state snapshot

Required file marker:

- `recallloom:file=rolling_summary`

Required metadata markers:

- line 2 must be a valid `last-writer` marker
- a valid file-state marker must appear in the leading metadata block
- the recommended protocol `1.0` writer position for the file-state marker is line 3
- helper-generated files currently place it on line 3
- current readers accept it within the first four lines as a compatibility tolerance, not as a relaxed writer contract

Language rule:

- marker `lang` must match `config.json.workspace_language`

Version rule:

- marker `version` must use a supported RecallLoom protocol version
- when `config.json.protocol_version` is supported, marker `version` should match it

Recommended sections:

1. Metadata header
2. Current State
3. Active Judgments
4. Risks / Open Questions
5. Next Step
6. Recent Pivots

Required section keys:

- `current_state`
- `active_judgments`
- `risks_open_questions`
- `next_step`
- `recent_pivots`

Required metadata header:

- line 1 must be the file marker
- line 2 must be a valid last-writer marker

Required last-writer marker shape:

```text
<!-- last-writer: [<tool_name>] | YYYY-MM-DD -->
```

Required file-state marker shape:

```text
<!-- file-state: revision=<n> | updated-at=<timestamp> | writer-id=<writer> | base-workspace-revision=<n> -->
```

Operational rule:

- if `state.json.workspace_revision` moves ahead of this file's `base_workspace_revision`, the summary may need review before it is trusted as current state

Validator rule:

- `rolling_summary.md` is invalid if the second line is missing or does not match the required last-writer marker format

Do not use it for:

- append-only history
- raw exploratory notes
- stale facts known to be false

## `STORAGE_ROOT/daily_logs/YYYY-MM-DD.md`

Role:

- append-only milestone evidence

Filename rule:

- the filename must use a valid ISO date in `YYYY-MM-DD.md` form

Required file marker:

- `recallloom:file=daily_log`

Required entry metadata:

- after the file marker, each milestone entry begins with a `daily-log-entry` marker
- helper-generated files place the first entry marker immediately after the file marker

Optional scaffold form before the first real entry:

- helper initialization may create a scaffold daily log
- scaffold logs use:
  - `<!-- daily-log-scaffold: true -->`
- scaffold logs are not counted as active entries
- scaffold logs still count as the latest active daily-log file for `state.json.daily_logs.latest_file`
- scaffold logs keep `latest_entry_id = null`, `latest_entry_seq = null`, and `entry_count = 0` until the first real append
- the first real append to a scaffold still becomes `entry-1`

Language rule:

- marker `lang` must match `config.json.workspace_language`

Version rule:

- marker `version` must use a supported RecallLoom protocol version
- when `config.json.protocol_version` is supported, marker `version` should match it

Required daily-log-entry marker shape:

```text
<!-- daily-log-entry: entry-id=<id> | created-at=<timestamp> | writer-id=<writer> | entry-seq=<n> -->
```

Entry unit rule:

- the file may contain multiple milestone entries
- each entry must carry its own `daily-log-entry` marker
- each entry must include the required daily-log sections
- append-only means adding a new entry block, not rewriting older entries in place

Entry sequence and id rule:

- `entry-seq` is a file-local sequence and must be contiguous as `1..N` inside each daily log file
- every daily log's first real append starts at `entry-seq=1`, including after an initialization scaffold is replaced by the first real entry
- helper-generated canonical `entry-id` is `entry-{entry_seq}` and is not a global identifier
- historical daily logs may each contain `entry-1`; duplicate `entry-id` values across different daily log files are normal under protocol `1.0`
- noncanonical ids can still be parsed, but validators should surface them with `noncanonical_daily_log_entry_id` so they are not confused with helper-generated canonical ids

Operational rule:

- helper appends should refuse stale writes when `state.json.workspace_revision` no longer matches the expected workspace revision
- entry sequences should remain contiguous inside the latest daily log
- helper append commands require an explicit target date; in normal use that date should be the latest active ISO-dated daily log suggested by preflight, or a newer ISO date when starting a new active day
- historical appends may be allowed explicitly, but they must not roll back the `state.json.daily_logs` latest-log cursor

Recommended entry shape:

- Work Completed
- Confirmed Facts
- Key Decisions
- Risks / Blockers
- Recommended Next Step

Required section keys:

- `work_completed`
- `confirmed_facts`
- `key_decisions`
- `risks_blockers`
- `recommended_next_step`

Do not use it for:

- every minor incremental update
- routine cold-start activity
- purely trivial edits

## `STORAGE_ROOT/update_protocol.md`

Role:

- recommended project-local override and extension layer

Presence rule:

- this file is generated by default by `init_context.py`
- for protocol `1.0`, it is recommended rather than strictly required
- when it is missing, validator should warn rather than fail the workspace

When this file exists, required file marker:

- `recallloom:file=update_protocol`

When this file exists, required metadata marker:

- a valid file-state marker must appear in the leading metadata block
- the recommended protocol `1.0` writer position is line 2
- helper-generated files currently place it on line 2
- protocol `1.0` readers accept it within the first four lines as a compatibility tolerance, not as a relaxed writer contract

Language rule:

- marker `lang` must match `config.json.workspace_language`

Version rule:

- marker `version` must use a supported RecallLoom protocol version
- when `config.json.protocol_version` is supported, marker `version` should match it

When this file exists, required section keys:

- `project_specific_overrides`

Use it when a project needs:

- custom read order
- custom write rules
- custom archive policy
- stronger local constraints

In protocol `1.0`, this file is a human-reviewed override layer.

That means:

- preflight, archive guidance, and bridge guidance should surface it clearly
- helpers should not silently ignore its existence
- helpers do not automatically execute its natural-language rules

Operational rule:

- cold-start flow should check this file before applying the default read order
- write-planning flow should check this file before choosing the final write set
- in the current package line, `preflight_context_check.py`, `archive_logs.py`, and bridge guidance surface this file for review rather than automatically executing its natural-language rules
- revision-aware write helpers (`commit_context_file.py`, `append_daily_log_entry.py`) do not reread or execute natural-language override prose automatically
- revision-aware helper commits should keep this file's `file-state` marker and `state.json.update_protocol_revision` in sync
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