document checkpoint policy · Entire

document checkpoint policy

8d47659·

pfleidi·3w ago·1 file·+35 added/-0 removed

Describe the checkpoint policy ref, schema, synchronization points, and hook behavior.

Sessions

20bac3016946View transcript

Changes

1

277 unmodified lines

278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318

277 unmodified lines

- `sessions` array in `CheckpointSummary` maps each session to its file paths
- `files_touched` is merged from all sessions

### Checkpoint Policy

Repo-wide checkpoint policy lives at `refs/entire/policies/checkpoint`. The ref
points at a commit whose tree contains `policy.json`:

```json
{
"checkpoint_version": "branch-v1",
"checkpoint_min_version": "branch-v1"
}
```

`checkpoint_version` is the checkpoint format new writes should use.
`checkpoint_min_version` is the oldest checkpoint format clients must be able
to read for this repo. Missing policy fields default to `branch-v1`.

Policy follows the configured checkpoint remote. `entire policy checkpoint`
fetche's the latest remote policy before validating requested changes, updates
the local policy ref, and pushes only `refs/entire/policies/checkpoint`.
Policy commits use the same signing settings as checkpoint commits.

Hooks that run while ordinary git operations must keep working offline:
post-commit and agent lifecycle hooks read only the local policy ref. If the
local policy requires checkpoint writes this CLI does not support, they skip
writing checkpoint data and warn only when running in an interactive terminal.
The pre-push hook is the regular online sync point: it compares the remote
policy ref with the local ref, fetches updated policy when needed, and evaluates
the refreshed policy before pushing `entire/checkpoints/v1`. If policy refresh
fails, the hook warns or logs the failure and lets the normal push continue.

User-driven commands warn when the local policy indicates the CLI should be
upgraded. Commands that need to decode checkpoint contents, such as
`entire checkpoint explain` and `entire session resume`, fail when the target
checkpoint uses an unsupported `checkpoint_version`.

### Checkpoint ID Linking

The checkpoint ID is the **stable identifier** that links user commits to metadata across branches.
```