Repo Context Ledger

Change lifecycle

1. Keep the session ID and epoch from start/resume; use status only when this task's identity or state needs resolving. Pass --session on lifecycle writes; never guess or absorb another task.
2. Follow an existing accepted plan. Run context/focus only for missing or changed background, not again for every ordinary-work turn. A known code boundary needs no repeated broad routing.
3. Start once when behavior will change and there is no suitable unfinished task: start --title "<title>" --feature <feature> --workflow <small-fix|ordinary-change> --tool <agent>. Reuse only a genuinely related task; never reopen a completed record to hide a new change.
4. Implement after verifying the routed boundary in code. Context docs guide where to look; they never justify reading too little code.
5. Choose acceptance goals before verification. Reads, searches, file/configuration generation, preparation, and authorized deployment use ordinary tools, not a verify wrapper per operation. Run acceptance through verify once when first needed; do not run it bare and repeat it just for a Ledger entry. Group related checks with an existing reviewed project script/preset, preserving step results and failure exit codes. Keep pre-deployment and post-deployment goals separate. Independent checks may run concurrently only without shared mutable resources; use direct argv, not nested shell strings.
6. Prefer an exact repository preset when configured. If PRESET_TRUST_REQUIRED appears, review it and repeat with its exact printed --trust-digest; never trust without reviewing. Ordinary operations and useful diagnostic observations belong in the same draft as such, not fabricated managed check results. Never replay a deployment, authorization, migration, or trade to obtain missing logging. See verification-presets.md for grouping and the optional tested script example.
7. A single-session small fix lets finish collect evidence. With parallel sessions or a broad dirty tree, run evidence --path for this task's paths only.
8. Refresh the related Pack and spec when their facts or dependencies changed. Update only the draft's new differences and correct superseded assumptions; retain useful earlier reasoning rather than rewriting unchanged background. A small-fix form still explains each meaningful change, its file/symbol references, and documentation rationale. Only Updated is generated; share common boundaries and verification rather than repeating them.
9. Remove unresolved template placeholders and finish once the bounded request is actually complete, not at every intermediate reply: finish --spec <spec>, or --no-spec --reason "<why no stable behavior exists>". Keep a returned continuation epoch on every resumed write.

Read production-workflow.md for large repositories, verification concurrency, PR baselines, coverage gates, and derived-index timing. Read writing-quality.md before editing an evidence-v1 draft.

Small is a known low-risk boundary, not a line count. Independent behavior changes, permissions, persistence, money, concurrency, public contracts, or uncertain impact need ordinary investigation and records. Expand the same draft when scope grows; preserve its notes and evidence, rather than finishing early or starting over. finish --dry-run is optional; do not make it a mandatory extra step or loop through it while still writing. Before finish, reconcile meaningful diff changes against the record; passing structural checks is not proof of complete business explanations.

Initialize or upgrade

Run init --dry-run, review the exact plan, then run the same init only when its scope is correct. Preserve prose outside managed markers and all existing completed history. Confirm adapters check, manifest check, and doctor. See document-model.md for legacy layouts and where facts belong.

Cross-window continuation

Before switching Agents or windows, run checkpoint --summary "<state>" --next "<action>"; use pause only when suspending the task. In the new window run plan --query "continue <keywords>", then its explicit resume action. Resume increments the epoch; it does not create a replacement session.

"Continue" inside the same active window is not a handover. If the task and current epoch are already known, continue directly; resume only for an actual handover, paused task, or state recovery.

If several sessions are close matches, choose an explicit session. If only foreign work overlaps, use committed Pack/spec/Change guidance. Private unfinished state does not travel with clone, pull, or another computer.

Integration and recovery

• Use doctor first for bounded read-only diagnosis. It never deletes locks or mutates Packs/sessions.
• At PR/integration time run policy --base <ref> for aggregate delta-based checks. Use audit --history --policy as-recorded --fail-on unresolved only for controlled historical/release audits, never to unblock an unrelated session.
• After merge, run sync --derived once on the configured default branch. Do not hand-edit generated indexes.
• Keep unfinished drafts private. Publish only through finish; never persist secrets or machine-specific absolute paths.

Runtime development

Edit src/repo_context_ledger/runtime.py.tmpl and its ordered source fragments, not generated runtimes. Run python scripts/build_runtime.py and python scripts/build_runtime.py --check; .context-ledger/ledger.py and the Skill runtime must remain byte-identical standalone files.