Frappucc1no/recall-loom / skills/recallloom
recallloom
FlaggedUse 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.
references/operation-playbooks.md
View on GitHub# Operation Playbooks
## Contents
- Project-Local Overrides
- Write Protocol Red Lines
- Public Surface Boundary
- Non-Invasive Defaults And UX Gates
- Cold Start
- Choose the Write Set
- Layered Write Judgment
- End-of-Day Update
- Compression
- Archive
- Daily-log Cursor Repair
- External-Writer Reconciliation
## Project-Local Overrides
If `STORAGE_ROOT/update_protocol.md` exists, read it before applying the default playbooks below.
Project-local overrides may:
- narrow the default read order
- strengthen write rules
- tighten archive behavior
- add stricter local constraints
They do not replace the core machine-readable contract.
For protocol `1.0`, this file is a human-reviewed override layer.
It is generated by default, but it remains a recommended override file rather than a strict workspace-validity requirement.
That means:
- preflight, archive guidance, and bridge guidance should surface it clearly
- helper scripts should not silently ignore that it exists
- helper scripts do not automatically parse or execute its natural-language rules
## Write Protocol Red Lines
- For normal managed sidecar mutations, use the applicable dispatcher surface: `write` for managed-file writes, `append` for daily-log entries, `sync-current-state-after-append` only when its post-append contract requires that lane, and `repair-daily-log-cursor` for cursor repair. The dispatcher invokes its internal helpers. Do not bypass it with blind file replacement, blind patching, hand-built sidecar files, or hand-invoked internal helpers.
- If a dispatched write fails, follow this order: diagnose the failure, fix the cause, obtain fresh dispatcher context, retry the dispatcher operation, then surface or return its blocked failure contract if it still cannot complete.
- Never hand-edit `STORAGE_ROOT/state.json` or `STORAGE_ROOT/config.json`. This includes `.recallloom/state.json` and `.recallloom/config.json`.
- For overwrite-style managed files, use dispatcher `write`, which performs the revision-aware internal commit; do not use blind file replacement.
- `append`, `write`, and `sync-current-state-after-append` may emit the bounded
`recallloom.transaction.compact/1.0` result with `--compact-json`. It is
mutually exclusive with legacy `--json`, preserves the exit code, contains
exactly one safe next action, and is under 2048 UTF-8 bytes. Do not apply it
to read, record, repair, bridge, or helper paths.
## Public Surface Boundary
Public package and release surfaces should contain only files a user needs to
install, understand, and operate the package.
Do not publish copied project memory, generated runtime output,
machine-local data, maintainer-only working files, or material that is not
required by the installable package.
Public CI and required checks validate repository contents and metadata only.
Do not describe them as proof of a user's local workspace state, host behavior,
or sidecar trust status.
## Non-Invasive Defaults And UX Gates
RecallLoom Core stays non-invasive by default.
- Do not require or auto-install hooks, daemons, watchers, MCP/plugin
enforcement, host adapters, telemetry/metrics, or remote payload transmission.
- Treat native command wrappers as opt-in convenience entrypoints over the same
dispatcher, not as an enforcement layer.
- Keep ordinary docs/source/planning edits outside the managed sidecar on a
silent allow or low-friction path unless they affect provenance-sensitive
RecallLoom state.
- For managed sidecar or provenance-impacting actions, route the operator UX
through `allow`, `warn`, `ask`, or `block`.
- Use `warn` for low-risk structural-only or readable legacy states; warnings
should be short, and repeated same-session low-risk warnings should be
cooldown-friendly.
- Use `ask` for legacy review / repair import or reviewed imported baseline
actions; require explicit operator confirmation before higher-risk writes.
- Use `block` for forged markers, detected receipt/store inconsistency, direct
`state.json` / `config.json` edits, privacy violations, and any general,
legacy, or unbound state classified as `inconsistent_or_tampered_evidence`.
- A general, legacy, or unbound `inconsistent_or_tampered_evidence` mutating
block is non-waivable. Use structural validation and the bounded current
provenance check; do not edit the sidecar, treat it as retryable, or use a
legacy recovery route to bypass the block.
- D5 is the only narrow transition from that failure family: it requires
helper-path evidence that is contract-valid for the current D5 schema, for a target-only post-hash read
failure or mismatch, an exact failure-time state match, and the fresh
binding, proposal, review, and expected-binding promotion checks. It is not a
waiver and does not prove cryptographic authorship. After promotion, run
fresh validate, status, and preflight before the first write.
- Do not present remote services, host memory, plugins, MCP, hooks, or wrappers
as authority for local helper evidence.
- In the current package line, receipt-backed mutation covers
dispatcher-issued managed-file writes, current latest-cursor daily-log
appends, and post-append summary sync.
Archive apply and bridge apply stay preview-only until they have their own
receipt-backed contracts.
- Daily-log cursor repair is a non-receipt-backed structural repair. It must not
write `derived/helper-receipts.json`, add a receipt operation, finalize a
mutating receipt, or claim historical daily-log origin. If the previous state
was `helper_evidenced`, preserve that label only when current bounded evidence
independently supports it; otherwise downgrade to structural/non-receipt-backed
provenance. Preserve `review_imported_baseline` as reviewed import, not helper
evidence.
## Cold Start
Use this flow whenever resuming a project with an existing RecallLoom structure.
1. Locate the project root.
2. Read `STORAGE_ROOT/config.json`.
3. Read `STORAGE_ROOT/state.json`.
4. Read `STORAGE_ROOT/rolling_summary.md`.
5. If `STORAGE_ROOT/update_protocol.md` exists, surface it for review before expanding beyond the minimum continuity set.
6. Read `STORAGE_ROOT/context_brief.md` only when the current task needs framing, scope, source-of-truth, or phase context that the summary does not already cover.
7. Read the latest active daily log only when milestone evidence, workday judgment, or external-writer reconciliation requires it.
8. Check whether newer artifacts exist than the maintained context files when freshness is uncertain or before a major write.
9. Prefer verified newer evidence over stale continuity files.
Read-side helpers may now also expose:
- `sidecar_trust_state`
- `provenance_state`
- `write_readiness`
- `expected_revisions`
- `preflight_contract_identity`
- `continuity_drift_risk_level`
- `allowed_operation_level`
Treat those as routing guidance for review vs write-readiness. They do not change the protocol file contract by themselves.
In the provenance MVP, `structurally_valid` and `review_imported_baseline` are not receipt-backed proof. Legacy sidecars without provenance baseline metadata are readable, but mutating helper writes must route through review / repair import first. Do not claim or persist `helper_evidenced` unless a mutating helper receipt was finalized successfully.
Default validate is structural and does not open `derived/helper-receipts.json`; receipt-store validation is an explicit operator lane with `--require-provenance --changed-only` or `--require-provenance --full`. The `--full` lane is currently bounded to current receipt-store evidence and is not a historical chain audit.
Cold start is for orientation, not for automatic rewriting.
Cold start should restore and recommend first.
It should not automatically continue `next_step` or execute unfinished project work without clear user confirmation.
## Choose the Write Set
Before writing anything, decide the smallest valid write set.
If `STORAGE_ROOT/update_protocol.md` exists, surface its project-local constraints for review before deciding.
Preflight guidance should expose two layers:
- primary write targets for deterministic current-state updates
- conditional review targets for files that may need review but are not default write targets
- revision context for safe helper writes
Typical mapping:
- `stable_rule` for durable workflow rules or source-of-truth routing that should be restored on the next cold start
- `STORAGE_ROOT/rolling_summary.md` for durable current-state changes
- `current_state` for what is true right now, including active judgments, risks, and the next step
- `STORAGE_ROOT/context_brief.md` for framing or phase changes
- `milestone_evidence` for releases, completed validations, or other durable milestones
- daily log for milestone events
Daily logs should only become write targets when the current session actually creates a new milestone entry.
Cross-day carryover by itself does not make the daily log a default write target.
If trust is only structural or drift risk is medium/high, prefer review-first or `no_write` over pushing ahead with a higher-risk mutation.
If only one file needs updating, update only that file.
Default exit modes before a write should stay explicit:
- `no_write` when no durable project fact changed
- `merge_current_state` when only current-state continuity changed
- `append_milestone` when the session created milestone evidence
- `defer` when the discussion is still unstable
- `confirm` when the action is historical, cross-boundary, or otherwise needs explicit confirmation
- `blocked` when the sidecar or safety contract is not trustworthy enough to write
## Proactive Recording Prompt
Use proactive recording prompts only after a durable milestone, accepted decision,
completed validation, release, or stable workflow rule becomes clear.
The prompt is a candidate, not a write:
- show a sanitized candidate summary
- suggest a `record --plan` path
- do not append, write, sync, repair, stage, commit, release, or update advisory state
- do not run as a daemon, watcher, hook, scheduled reminder, or background listener
- stay silent during unstable exploration, drafts, ordinary debugging, or explicit
"do not record" requests
- block instead of suggesting a path when the candidate includes sensitive content,
private evidence, raw attached text, secrets, personal data, or local absolute paths
`record --suggest` is the side-effect-free helper lane for this prompt. A later
record still has to pass `record --plan`, preflight, privacy, revision/cursor,
support, and receipt/provenance gates.
## Layered Write Judgment
The agent is responsible for judging the meaning of prepared continuity content.
Helpers may provide safe write context, freshness state, revision guards, and static write-tier guidance, but helpers must not classify the content or decide the semantic layer for the agent.
Use this playbook before editing `context_brief.md`, `rolling_summary.md`, or a daily log.
### Five Judgment Questions
Ask these in order:
1. Does this contain a new durable fact?
- If not, choose `no_write`.
2. Would a future cold start need this before reading current state?
- If yes, consider `stable_rule`.
3. Does this describe what is true now, including phase, risk, active judgment, or next step?
- If yes, consider `current_state`.
4. Does this record completed, accepted, or validated evidence from this session?
- If yes, consider `milestone_evidence`.
5. Is the layer boundary uncertain?
- If yes, choose `defer` or `confirm` instead of guessing.
### Layer Signals
| Candidate type | Default target | Positive signal | Common wrong move |
|---|---|---|---|
| `stable_rule` | `context_brief.md` | Long-lived workflow rule, source-of-truth routing, project boundary, cross-session recovery fact | Putting the rule only in `rolling_summary.md` because it was discovered during current work |
| `current_state` | `rolling_summary.md` | Current phase, active risk, active judgment, current blocker, next step | Promoting short-lived state into `context_brief.md` because it feels important |
| `milestone_evidence` | daily log | Accepted decision, completed validation, release, handoff milestone | Using the daily log as the only place where the next session can recover current state |
| `no_write` | no file | Explanation of existing facts, trivial read, repeated confirmation, no durable change | Writing just because the conversation happened |
| `defer` / `confirm` | no file until resolved | Unstable discussion, historical append, cross-boundary action, unclear ownership | Guessing a layer and writing anyway |
### Conflict Rules
When signals point to more than one layer, do not vote by keyword.
Use this order:
1. Decide whether nothing should be written.
If there is no new durable fact, use `no_write`.
2. Extract stable rules first.
A stable rule should contain only the durable rule, source-of-truth route, boundary, or workflow constraint.
3. Extract current state next.
Current state should contain only what matters for the next active step, risk, phase, or judgment.
4. Extract milestone evidence last.
A daily log entry records what happened; it does not replace the stable rule or the current-state snapshot.
5. Stop on low confidence.
If the agent cannot explain the layer in one sentence, choose `defer` or `confirm`.
Multi-layer overlap means `multi_layer_split`: split different facts across layers.
Do not copy the same sentence into multiple files.
### Lightweight Self-Review
The self-review should stay short and can remain internal unless the user asks, the write is high-risk, or the session is being handed off.
```text
Candidate content: <one-sentence summary>
Recommended layer: <no_write | stable_rule | current_state | milestone_evidence | multi_layer_split | defer | confirm>
Reason: <one sentence about recovery priority, current truth, or evidence value>
Split note: <write "none" or list what each layer carries>
```
### Anonymized Calibration Cases
These cases are calibration examples for agent judgment.
They are not project facts and should not be copied into a workspace sidecar.
| Case | Correct judgment | Wrong judgment to avoid |
|---|---|---|
| A team confirms that all customer deliveries must complete one approval checklist before handoff | `stable_rule -> context_brief.md`; if the decision was accepted in this session, also record milestone evidence | Only writing the rule into `rolling_summary.md` |
| The current delivery still has two approval checks left and the next step is to finish them | `current_state -> rolling_summary.md` | Promoting a short-lived task into `context_brief.md` |
| A validation batch passed today | `milestone_evidence -> daily log`; if it changes current readiness, summarize that current state | Putting validation details into `context_brief.md` |
| The user suggests a possible workflow change but does not approve it | `defer` or a current-state open question | Writing the unapproved idea as a stable rule |
| The agent only explains an existing rule and no new fact is created | `no_write` | Appending a daily log entry just because the explanation happened |
| A one-off command, temporary path, or short debugging action is used | Usually `no_write`; if it blocks active work, briefly capture current state | Recording the temporary action as a stable rule or milestone |
| A long-term rule is accepted and a short-term follow-up task is created in the same session | `multi_layer_split`: rule to `context_brief.md`, follow-up to `rolling_summary.md`, accepted decision to daily log if milestone-worthy | Copying one combined sentence into every layer |
| A research chapter adopts a source-citation rule, but the current chapter still lacks sources | Rule to `context_brief.md`, current gap to `rolling_summary.md`, accepted decision to daily log if needed | Only writing the daily log and losing the rule on cold start |
| A design review entry moves from notes into a fixed index | Entry route to `context_brief.md`, current sync task to `rolling_summary.md` | Treating the fixed route as a one-time task and losing it later |
| A date-sensitive append matches the heuristic suggestion, but local rollover or timezone notes still require a human check | `confirm`: keep the proposed date visible and require explicit review before writing | Treating a matching preferred date as automatic approval |
## Package Support Gate
Before a helper proceeds, it may perform the daily package-support check described in `package-support-policy.md`.
- `supported` and `upgrade_recommended` do not block actions
- offline with no support cache returns `unknown_offline` and allows local diagnostic, read-only, and mutating actions; network access is not a local-use prerequisite
- a structurally valid stale cache is re-evaluated against the current package version and continues its cached support restriction offline
- an invalid or uninterpretable cache is distinct from a missing cache and permits diagnostic actions only while offline
- a valid online advisory takes precedence over an invalid cache, atomically repairs it, and returns a machine-readable cache-repaired diagnostic
- invalid-cache `package_support` guidance uses public-safe machine reasons and directs the operator to a read-only diagnostic, online refresh and atomic replacement, or removal of the invalid package-scoped local cache before retrying; it does not treat package upgrade as cache repair or claim tampering
- malformed online or configured advisory input remains `invalid_support_advisory`; correct or refresh the advisory instead of applying invalid-cache cleanup guidance
- `readonly_only` blocks mutating helpers but permits diagnostic and read-only helpers
- `diagnostic_only` permits diagnostic helpers only
- dispatcher may share the same-day support payload through `RECALLLOOM_SUPPORT_STATE_JSON`, but child helpers still authorize from cache or advisory state instead of trusting env payloads alone
- support cache is user-scoped and package-path-scoped, never stored in the project sidecar
- the cache is structurally validated but non-authenticated local policy data; it does not resist a local writer and is not a permission boundary, tamper-proof record, or authenticated remote witness
If a package support gate blocks the action, stop and surface the returned failure contract instead of falling back to manual file edits.
When deterministic write safety matters, use this flow:
1. prepare the content change outside the managed file
2. use dispatcher `write` for `rolling_summary.md`, `context_brief.md`, or
`update_protocol.md`
3. use dispatcher `append` for a daily-log milestone entry
4. let the dispatcher run its fresh preflight and invoke its internal helper
only after the relevant gates authorize the operation
For normal operations, use only the applicable dispatcher surface: managed-file
writes and daily-log entries use `write` and `append`, while
`sync-current-state-after-append` is used only when its post-append contract
requires that lane. Do not invoke `commit_context_file.py` or
`append_daily_log_entry.py` by hand. Those helpers
are internal dispatcher/integration surfaces. Dispatcher runs its own fresh
preflight, constructs the binding, and persists the matching lease immediately
before calling a helper. A read-only `preflight_context_check.py <project>
--json` result does not issue either material, and there is no independent
operator binding/lease pickup interface. A hand-invoked helper without the
still-current dispatcher-issued material is expected to fail; do not synthesize,
copy from preflight output, reuse, or amend it.
For the first write from `review_imported_baseline`, use dispatcher `write` or
`append` with the existing `--confirm-review-imported-baseline` confirmation;
the dispatcher issues the confirmation-bound binding plus matching lease. The
existing `sync-current-state-after-append` lane also accepts that confirmation
when its own post-append contract requires it. The internal helpers do not
accept a confirmation flag and only consume dispatcher-issued material.
### D5 Human Material And Promotion
Use this lane only after `recallloom.py validate <project> --json
--require-provenance --changed-only` returns a current D5
`inconsistent_review_binding_digest`. The validation is read-only. If it does
not return that digest, remains blocked, or later changes, do not stage or
promote D5 material.
Prepare complete proposal and review documents. The following copyable
skeletons include every ordinary required heading, the ordinary promotion-target
and hint-only checks, and exactly one D5 JSON fenced block in its required
section. Replace every angle-bracket placeholder with public-safe, human-reviewed
content. The `accept` review example is valid only after the operator has
actually completed the human review; do not use it to choose an outcome
automatically.
Proposal skeleton:
````markdown
# Source summary
<public-safe summary of the current D5 evidence>
# Source type and confidence
<human assessment of source type and confidence>
# Candidate current-state facts
<candidate fact, or none>
# Candidate milestone events
<candidate event, or none>
# Candidate judgment reversals
<candidate reversal, or none>
# Candidate next-step changes
<candidate next step, or none>
# Conflicts with current sidecar
<identified conflict, or none>
# Suggested promotion actions
Target: rolling_summary.md
```json
{
"schema_version": "1.0",
"material_type": "inconsistent_recovery_proposal",
"inconsistent_review_binding_digest": "sha256:<64-lowercase-hex>",
"proposed_action": "accept_current_target_as_reviewed_baseline"
}
```
# Review conclusion
<human review is required before any promotion>
````
The proposal's D5 block must remain under `Suggested promotion actions` (or
`建议提升动作`) and have exactly these keys:
```json
{
"schema_version": "1.0",
"material_type": "inconsistent_recovery_proposal",
"inconsistent_review_binding_digest": "sha256:<64-lowercase-hex>",
"proposed_action": "accept_current_target_as_reviewed_baseline"
}
```
Review skeleton (use its `accept` values only after human review has accepted
the same bound material):
````markdown
# Proposal reference
<staged proposal filename>
# Review outcome
accept
# Approved items
<human-approved item>
# Rejected items
<none, or a human-rejected item>
# Promotion status
No items remain hint-only.
```json
{
"schema_version": "1.0",
"material_type": "inconsistent_recovery_review",
"inconsistent_review_binding_digest": "sha256:<64-lowercase-hex>",
"decision": "accept",
"accept_current_target_as_reviewed_baseline": true
}
```
# Next action
<run promotion only when this complete review is accepted>
````
The review D5 block must remain under `Promotion status` (or `提升状态`) and
have exactly these keys. For promotion, its digest must be character-for-character
the same as the proposal digest, and its ordinary review outcome must also
classify as `accept`.
Unknown or duplicate keys, a duplicate D5 block, a block in another section,
or free text used instead of this JSON block are rejected. Stage the prepared
proposal, then record the prepared review and promote in the same command:
```bash
python skills/recallloom/scripts/stage_recovery_proposal.py <project> \
--source-file <prepared-d5-proposal.md> --json
python skills/recallloom/scripts/record_recovery_review.py <project> \
--proposal-file <staged-proposal-file> \
--source-file <prepared-d5-review.md> \
--expected-inconsistent-review-binding-digest sha256:<64-lowercase-hex> \
--json
```
`<staged-proposal-file>` is the staged filename returned by the first command,
and the digest in the second command and both JSON blocks is the exact current
digest returned by validation. Any target, state, store, revision, material, or
binding change blocks promotion with no state promotion.
## End-of-Day Update
Use an end-of-day update when:
- meaningful progress happened
- the user explicitly signals stop-work
Typical order:
1. rolling summary
2. `context_brief.md` if needed
3. today's daily log
If the day simply carried over and no milestone happened, the valid result can still be:
1. update only `rolling_summary.md`
2. or exit with `no_write`
End-of-day writes must leave a clear next-step note unless the valid result is `no_write` or `blocked`.
## Compression
Compress `rolling_summary.md` when it becomes hard to scan.
The compression rule is:
1. keep current state
2. move supporting detail to the daily log
3. drop stale or false content
4. preserve the next step and unresolved risks
Compression should make the file easier to resume from, not more abstract.
## Archive
Archive old daily logs when:
- the log set grows too large
- a major phase boundary is crossed
Archived logs should remain retrievable on demand, but fall out of the default cold-start path.
Archive is preview-only in the current public package contract. Do not move
files or present an archive apply command as available until archive has its own
receipt-backed contract.
Recommended behavior:
- preview targets first
- refuse the preview if archive-target collisions are detected
- if `update_protocol.md` exists, surface it for review before archiving
Bridge work follows the same public boundary: use dispatcher `bridge` only for
preview and review the candidate target. Do not document or rely on
`bridge --yes`; bridge apply is not a supported public operation in this
package line.
## Daily-log Cursor Repair
Use `repair-daily-log-cursor` only when validation or helper output shows that
`state.json.daily_logs` no longer matches the latest active daily log.
Operator flow:
1. run `recallloom.py repair-daily-log-cursor <project-path> --json`
2. review `current_cursor`, `expected_cursor`, `repair_eligible`,
`preview_digest`, confirmation material, and `next_action`
3. if repair is intentional, rerun with `--apply --yes` and a fresh preview
binding: `--expected-workspace-revision` or `--preview-digest`
4. rerun preview, status, validation, or the blocked write path that originally surfaced
the cursor mismatch
Repair rules:
- preview is read-only; apply is mutating and must pass the support gate
- apply updates cursor state from parser evidence instead of editing daily-log
content
- apply must refuse stale preview digests or missing preview bindings
- the repair does not create helper receipts or claim historical helper origin
- if a failure payload includes `safe_to_retry: false` or a non-`none`
`trust_effect`, follow `single_next_command` or validation guidance before
retrying a write
## External-Writer Reconciliation
If another tool or session may have updated the files:
1. reread current files
2. identify new facts or judgments
3. merge before writing
4. never discard append-only milestone entries
The goal is conservative continuity, not aggressive overwriting.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| 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: 115k | Updated | Claude CodeCodex | Verified | Install |
| 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: 115k | Updated | Claude CodeCodex | Verified | Install |