Checkpoint Protocol

A cross-skill convention for session persistence. Any skill that runs multi-step workflows across conversations adopts this protocol to save, resume, and recover state without the user re-explaining context.

This is a protocol, not a skill. It defines a file format, naming convention, resume behavior, and integration contract that individual skills implement. Think of it like HTTP — the spec lives here, the implementations live in each skill.

Two versions, don't confuse them

• `protocol_version` — the on-disk schema version, currently "1.1". It

lives inside every checkpoint file and only changes when the file shape grows in a way the validator must know about. The validator (scripts/checkpoint.mjs) enforces it and accepts both `"1.0"` and `"1.1"`.

• Skill release version — the version in this file's YAML frontmatter. It

tracks the evolution of the docs and tooling (the pm_refs extension, the doctor/next commands, etc.) and moves independently, in lockstep with the rest of the catalog. oc-release-ops bumps it.

Additive fields, two ways to ship them. An optional additive field can ride under the same wire version — pm_refs (skill release 1.2) was added under schema "1.0" with no wire bump, because old checkpoints stayed valid and the shape only grew. OR a release can group additive fields into a marked minor wire bump when it wants a visible protocol revision. v1.6 ("the instrumented pipeline") took the second path: cost, eval_scores, and telemetry_handle landed together as wire `"1.1"`. It is still fully backward compatible — "1.0" checkpoints validate unchanged, those three fields stay optional — the 1.1 stamp just marks the revision. New writes stamp "1.1"; oc-migration-ops sweeps existing "1.0" files forward. A wire bump is never a breaking change here: it only ever adds optional fields, never removes or repurposes one.

Problem Statement

Claude's context resets between conversations. Multi-step skills (oc-app-architect, oc-reverse-spec, oc-stack-forge, oc-code-auditor, oc-deploy-ops, oc-git-ops) lose all progress when a session ends unless they write it down. Before this protocol (v1.0), oc-reverse-spec kept a bespoke checkpoint.md, oc-app-architect had gates but no session persistence, and most skills had no continuity at all.

Each skill reinvented (or didn't) its own persistence, and the user paid the cost: re-explaining context, re-reading files, and hoping Claude picked up where it left off. This protocol gives every skill one shared format instead.

Core Concepts

1. The Checkpoint File

Every checkpoint-aware skill writes a single checkpoint.json file to its project directory. JSON (not markdown) because it's machine-parseable for cross-skill reads.

Location: {project-dir}/.checkpoints/{skill-name}.checkpoint.json

Example paths:

/home/claude/storefront/.checkpoints/oc-app-architect.checkpoint.json
/home/claude/storefront/.checkpoints/oc-code-auditor.checkpoint.json
/home/claude/storefront/.checkpoints/oc-reverse-spec.checkpoint.json

Multiple skills can checkpoint the same project simultaneously without collision.

2. Checkpoint Schema

{
  // === HEADER (required) ===
  "protocol_version": "1.1",             // On-disk schema version — stamp new writes "1.1"; validator also accepts "1.0"
  "skill": "oc-app-architect",              // Skill that owns this checkpoint
  "project": "storefront",               // Human-readable project name
  "project_dir": "/home/claude/storefront",  // Absolute path
  "created_at": "2026-03-31T14:00:00Z",
  "updated_at": "2026-03-31T15:30:00Z",

  // === PROGRESS (required) ===
  "phase": "build-loop",                 // Current phase name (skill-defined)
  "step": "sprint-2-eval-round-1",       // Current step within phase
  "status": "in_progress",               // in_progress | blocked | complete | failed
  "progress_summary": "Sprint 1 passed (8.2/10). Sprint 2 generator built, evaluator running.",

  // === PROGRESS TABLE (recommended; validator warns if missing while in_progress) ===
  // Ordered list of all phases/steps with completion status
  "progress_table": [
    { "id": "planning",       "label": "Planner",          "status": "complete" },
    { "id": "sprint-1",       "label": "Sprint 1: Auth",   "status": "complete" },
    { "id": "sprint-2",       "label": "Sprint 2: CRUD",   "status": "in_progress" },
    { "id": "sprint-3",       "label": "Sprint 3: UI",     "status": "not_started" }
  ],

  // === CONTEXT PRIMER (recommended — this is what lets resume skip a full re-read) ===
  // Dense, self-contained summary. A new session reads ONLY this + generated files
  // to resume work. Must be complete enough that re-reading the full codebase or
  // re-running prior phases is unnecessary.
  "context_primer": {
    "key_decisions": [
      "Stack: Hono + D1 + Workers. Auth: WebAuthn passkeys.",
      "Two users: Alex (admin), Sam (viewer). User IDs in D1.",
      "Sprint 1 delivered auth + session middleware. All tests pass."
    ],
    "generated_files": [
      "spec.md",
      "sprint-plan.md",
      "sprints/sprint-1/contract.md",
      "sprints/sprint-1/eval-round-1.md",
      "sprints/sprint-1/eval-round-2.md",
      "src/auth/passkey.ts",
      "src/middleware/session.ts"
    ],
    "user_preferences": [
      "Prefers table-based layouts",
      "Terminal/dark aesthetic",
      "Direct, concise communication"
    ]
  },

  // === BLOCKERS & OPEN QUESTIONS (optional) ===
  "blockers": [
    {
      "id": "b1",
      "description": "Evaluator flagged missing rate limiting on auth endpoints",
      "blocking": "sprint-2",
      "needs": "user_decision",  // user_decision | code_fix | external_dep
      "proposed_resolution": "Add rate-limit middleware in sprint 2 scope"
    }
  ],

  // === NEXT ACTIONS (required while status is in_progress — resume reads [0] first) ===
  // What the next session should do FIRST. Ordered by priority.
  // Each item is a string, or { "text": "...", "done_when": "<shell cmd>" } so a
  // session can self-verify completion. `checkpoint done <skill>` pops item [0].
  "next_actions": [
    "Read evaluator report: sprints/sprint-2/eval-round-1.md",
    "Fix rate limiting gap flagged in blocker b1",
    { "text": "Re-run evaluator on sprint 2", "done_when": "npm test" }
  ],

  // === SKILL-SPECIFIC STATE (optional) ===
  // Freeform object for skill-internal state that doesn't fit the schema above.
  // Private to the owning skill: siblings read only keys its owner documents for them.
  "skill_state": {
    "current_sprint": 2,
    "iteration": 1,
    "max_iterations": 3,
    "pass_threshold": 6.0,
    "scores": {
      "sprint-1": { "final": 8.2, "rounds": 2 }
    }
  }
}

3. Status Values

Two enums, deliberately. The top-level status is one of the four above. Individual progress_table[].status rows use a superset that also allows not_started — a single phase can be not-started even though the checkpoint as a whole is in_progress. The validator enforces each set in its own place.

Resume Protocol

When any checkpoint-aware skill is invoked and a checkpoint exists for the current project, follow this sequence:

Step 1: Detect

Check: {project-dir}/.checkpoints/{skill-name}.checkpoint.json exists?
  YES → read it, go to Step 2
  NO  → start fresh (normal skill flow)

Step 2: Orient

Read the checkpoint. Display a brief status to the user:

RESUMING: [skill] on [project]
Last session: [updated_at, relative time]
Status: [status] — [progress_summary]
Progress: [X/Y phases complete]
Next: [first item from next_actions]

Step 3: Confirm (only when there's something to confirm)

Resuming your own work shouldn't cost a question every time. Default behavior:

• `status: in_progress` and not stale → continue automatically. Just say

"Resuming from next_actions[0]: …" and proceed. The user can always redirect.

• `status: blocked` or `failed`, or the checkpoint is stale (untouched for more

than 7 days while in_progress, 14 days while complete, or 3 days while blocked) → stop and ask: "Continue from here, restart, or show the full checkpoint?" These are the cases where silently continuing is wrong.

• Continue → Read context_primer and next_actions, load referenced

generated_files, proceed.

• Restart → Archive the current checkpoint to

.checkpoints/history/<skill>.<timestamp>.checkpoint.json (what checkpoint.mjs reset <skill> does; tracked in git like the checkpoint itself), then start fresh.

• Show full → Display the complete checkpoint for review, then ask continue/restart.

Step 4: Prime Context

Before doing any new work:

1. Read context_primer.key_decisions — this IS your session context
2. Read context_primer.generated_files — but only the ones relevant to the

current step (don't read all files from all sprints if you're on sprint 3)

1. Check blockers — if any are needs: user_decision, ask before proceeding
2. Start with next_actions[0]

Step 5: Re-validate (optional but recommended)

If the checkpoint is >24h old, do a quick consistency check:

• Do the referenced files still exist at the expected paths?
• Does the project directory structure match what the checkpoint expects?
• Flag any drift: "Checkpoint references src/auth/passkey.ts but the file has

been modified since the last session. Want me to re-read it?"

Write Protocol

When to Write

Checkpoint writes are mandatory lifecycle work, not optional bookkeeping. Update the checkpoint after:

If a future session would be misled without the write, the current skill must write before handing control back.

How to Write

You do not need any special tooling to write a checkpoint — your own file tools are the writer. The scripts/checkpoint.mjs CLI described under Tooling is an optional convenience that exists only inside the opchain.dev repo; on a user's own project it is absent, and you write checkpoints directly instead. Do not treat a missing CLI or a missing npm run checkpoint:* script as a reason to skip the write. Do not tell the user that status is unreliable merely because generated CLI output is unavailable: read the checkpoint JSON directly, then corroborate its claims against the referenced specs, git state, tests, and release artifacts. Record CLI adoption as tooling debt only when the user actually wants that convenience added.

The operation is always read → merge → write, four concrete steps you perform with the tools you already have:

1. Ensure the directory exists. Create {project-dir}/.checkpoints/ if it isn't

there yet — mkdir -p {project-dir}/.checkpoints with the Bash tool, or just rely on your Write tool creating parent directories. ({project-dir} is the root of the project you're working in — the directory that holds its .git, package.json, or src/ — not the skill's install directory.)

1. Read what's there. Read {project-dir}/.checkpoints/{skill-name}.checkpoint.json

if it exists; treat a missing file as {}.

1. Merge, don't clobber. Merge your new state into the existing object and set

updated_at to the current time (ISO-8601). Never blindly overwrite — another skill may have written a sibling checkpoint, and this file may have been hand-edited.

1. Write the JSON back to the same path with the Write tool. Include at least the

required header + progress fields from the schema above (protocol_version, skill, project, project_dir, created_at, updated_at, phase, step, status, progress_summary, and — while in_progress — next_actions), and stamp protocol_version as "1.1".

# The shape of the operation — do it with your own Read/Write tools, no CLI required:
existing = read_json("{project-dir}/.checkpoints/{skill}.checkpoint.json") or {}
updated  = merge(existing, new_state)
updated["updated_at"] = now()          # ISO-8601
write_json("{project-dir}/.checkpoints/{skill}.checkpoint.json", updated)

A hand-written checkpoint is a first-class checkpoint. If the CLI happens to be present (you're in the opchain repo), it automates the merge and validates the result — use it. Everywhere else, the four steps above ARE the protocol. The one unacceptable outcome is ending a session with state that a future session needed but that was never written to disk.

Checkpoint Size

There is no hard byte cap — these are session-state docs, and an honest one beats an artificially short one. (An earlier draft of this protocol said "under 4KB"; real checkpoints run 5–16KB and that's fine. .checkpoints/README.md is the authority: keep them readable, keep them honest.)

What actually matters is keeping the resumable core scannable and stopping append-only telemetry from growing without bound:

• progress_summary is read on every resume — keep it to a few sentences. The

validator warns above ~1200 characters. Push detail into progress_table.

• If context_primer.key_decisions exceeds ~20 items, consolidate older ones into

a summary paragraph and keep only the recent items individually.

• Per-session telemetry in skill_state (merged-PR lists, reconciliation logs) is

the usual source of bloat and of merge conflicts. Rotate closed sessions into .checkpoints/history/<skill>.<timestamp>.json instead of letting skill_state grow. The validator warns once a file passes ~32KB.

Anti-pattern (worked example): don't auto-stamp `merged_prs` per merge. opchain.dev once ran a .github/workflows/checkpoint-after-merge.yml that, on every merge to main, appended the merged PR to skill_state.merged_prs and opened a bot/checkpoint-stamp-<PR> PR. It was removed 2026-06-22 after two compounding failures: (1) under branch protection the bot's gh pr merge --auto could never satisfy required review, so each merge left a permanent open PR (two dozen piled up); and (2) every stamp PR appended to the same array, so they mutually conflicted — merging one staled the rest, and GitHub's server-side resolution bypasses the merge driver (see Tooling). merged_prs is fully reconstructable from git log; it is not worth a CI-gated PR per merge. Restamp oc-git-ops at inflection points by hand (the assistant does this — e.g. a single reconciliation PR), and rotate the array into .checkpoints/history/.

Cross-Skill Reads

Skills can read each other's checkpoints (read-only) for coordination. The table below is illustrative — the maintained upstream/downstream map lives in orchestrator.md § "Upstream/Downstream Map", which has a row for every skill in the catalog. Treat that as the single source of truth; this table is just the common cases.

Rules:

• Read the header, progress, progress_table, context_primer, and blockers
• Don't read another skill's skill_state unless its owner documents that key for

siblings (in the owner's Cross-Skill Reads / "Read by" table or its schema section). A documented key is a published contract its owner keeps stable; everything else is private. The commit gate is one such reader: it reads oc-bug-check's skill_state.last_run_verdict (or last_run.verdict) and skill_state.verified_tree per oc-bug-check's § Commit gate contract. (The opchain repo's checkpoint doctor also scans every skill_state for merged/shipped tokens when flagging stale next actions; it relies on no shape.)

• Never write to another skill's checkpoint
• If you need to coordinate, write to your own checkpoint and reference the other:

"depends_on": "oc-app-architect checkpoint shows spec approved at 2026-03-31T12:00:00Z"

Tooling (optional — bundled project helper)

The oc-checkpoint-protocol skill includes scripts/checkpoint.mjs. Resolve that path relative to this skill's installed SKILL.md and run its absolute path from the consuming project:

node /absolute/path/to/oc-checkpoint-protocol/scripts/checkpoint.mjs status
node /absolute/path/to/oc-checkpoint-protocol/scripts/checkpoint.mjs validate

The launcher finds the consuming Git repository root, even from a subdirectory; outside Git it uses the current directory. An explicit OPCHAIN_ROOT overrides discovery. State stays in the consuming project's .checkpoints/, never in the skill installation or plugin cache. The same commands below work with this bundled path substituted for scripts/checkpoint.mjs; no npm setup is needed. Installing or updating the helper must not initialize or overwrite checkpoints.

This entire section is an optional fast-path, not a requirement. The commands below use the opchain.dev source repo's scripts/checkpoint.mjs and checkpoint:* npm aliases. In installed projects, use the bundled helper above. If that helper is unavailable, you still create, read, and update checkpoints directly with your file tools (see How to Write above). If any command in this section is not found, skip it and write the file yourself; a missing scripts/checkpoint.mjs is never a reason not to checkpoint.

When they are available, these commands automate the read → merge → write and validate the result. scripts/checkpoint.mjs is zero-deps pure Node.

Two companion guides ship in this skill's own directory (they are not bundled into the other skills): references/INTEGRATION.md, the per-skill integration guide, and references/WALKTHROUGH.md, an end-to-end resume walkthrough. The executable wire-1.1 lifecycle, typed-handoff, and atomic-store interfaces are specified in references/state-contract-v1.md; existing 1.0/1.1 checkpoints remain valid.

Read / resume:

node scripts/checkpoint.mjs status            # "where did I leave off?" — full summary
node scripts/checkpoint.mjs status <skill>    # one checkpoint; exits 1 when that skill has none
node scripts/checkpoint.mjs status --brief    # just the top skill + its next action + blockers
node scripts/checkpoint.mjs status --since=2026-06-01T00:00:00Z   # momentum digest
node scripts/checkpoint.mjs next              # the SINGLE highest-priority non-stale action

status leads with a ⛔ N decisions waiting on you banner when any blocker needs: user_decision, and flags ⚠ stale (Nd) on checkpoints untouched for more than 7 days (in_progress), 14 days (complete) or 3 days (blocked). next encodes the priority hierarchy (blocked-on-decision > failed > in_progress-at-gate > in_progress > complete-with-queued-work > not-started) so you don't need the oc-orchestrator's registry to answer "what now?".

Reconcile / verify (catch drift before it bites):

node scripts/checkpoint.mjs doctor            # cross-check vs git history + filesystem
node scripts/checkpoint.mjs doctor --online   # also compare deployed /api/health vs the approved release baseline
node scripts/checkpoint.mjs doctor --fail-on-warnings

doctor flags: a project_dir that doesn't exist on this machine, stale in_progress checkpoints, generated_files that reference missing paths, and next_actions that point at PRs/tickets already merged (the "telling future-self to redo shipped work" failure that caused three manual reconciliations in this repo).

next uses the same drift evidence before recommending work. If a queued action references already-merged PR work or a completed ticket, next skips to the first fresh action or recommends checkpoint reconciliation instead of telling the next agent to redo shipped work.

Write:

npm run checkpoint:validate                   # schema gate — CI runs this (add --strict to fail on warnings)
node scripts/checkpoint.mjs list              # list all checkpoint files
node scripts/checkpoint.mjs show [skill]      # display full JSON for one/all checkpoints
node scripts/checkpoint.mjs reset <skill>     # archive current file into .checkpoints/history/
node scripts/checkpoint.mjs update <skill> --field=value [...]   # apply updates, auto-stamp updated_at
node scripts/checkpoint.mjs done <skill>      # pop next_actions[0] → recently_done, restamp
node scripts/checkpoint.mjs init              # scaffold .checkpoints/ on a fresh project

update supports three operators on dotted paths:

• --key=value — replace a scalar
• --key+=value — append to an array (creates if missing)
• --key:json=... — parse the value as JSON for objects/arrays/numbers

+ and :json combine in either order (--key:json+= or --key+:json=). An append adds its value as one element, so pass an object to add one entry. A key that still carries an operator after those are read is refused, rather than written as a literal key.

The validator runs after every update/done so you can't silently corrupt a file. Timestamps accept Z or a numeric offset (+00:00); the CLI writes Z.

Mutating CLI commands (update, done, and reset) serialize per skill with the same process-owned advisory-lock policy as local MCP, and checkpoint writes use same-directory temporary files plus atomic rename. Concurrent append updates therefore merge against the latest accepted record instead of overwriting one another; a killed writer leaves the prior accepted JSON intact. This remains a single-file, zero-package-dependency CLI when copied elsewhere. Atomic mutation supports macOS with /usr/bin/lockf and Linux with flock on PATH; unsupported hosts fail explicitly rather than falling back to unsafe stale-lock recovery.

The opchain repository's Claude Code Stop hook additionally derives its enforced skill inventory from skills/, normalizes namespaced Skill-tool invocation IDs, and requires the checkpoint's record_updated_at ?? updated_at to be at or after the transcript invocation event. Its stop_hook_active guard prevents a block loop. This current-run enforcement belongs to that repo-local hook; raw skill installs, MCP clients, and the distributed plugin do not gain it implicitly.

Merge-driver caveat (read this). .gitattributes registers a custom merge driver (scripts/merge-checkpoint.mjs) that auto-resolves telemetry-only conflicts. It runs on local `git merge` only — GitHub's server-side "Update branch" / auto-merge buttons do not invoke it. A checkpoint that conflicts there can produce invalid JSON and fail CI (this happened, 2026-05-15). Mitigations: rotate volatile telemetry out of the CI-gated file (see Checkpoint Size), and prefer resolving checkpoint conflicts with a local git merge so the driver runs. node scripts/checkpoint.mjs validate after any manual conflict resolution catches the broken-JSON case before you push.

Scaffold Phase

This protocol is not invoked directly (it has no commands of its own). Scaffolding a fresh project is deliberately trivial and needs no tooling:

• Any skill that is about to write its first checkpoint and notices there's no

.checkpoints/ directory simply creates it (mkdir -p {project-dir}/.checkpoints, or lets the Write tool create it) and writes the file, per How to Write. That is the whole scaffold — a directory and a JSON file.

• The oc-orchestrator cold-start (/oc-ops on a project with no .checkpoints/)

does the same thing as step zero.

That is all a user's project ever needs. Everything below is opchain-repo-only convenience and is not required to use the protocol on your own project:

1. scripts/checkpoint.mjs — an optional validator/status/next/doctor/update CLI that

automates the read→merge→write. If you want it on another repo you can copy it from the opchain.dev reference implementation, but nothing here depends on it.

1. .checkpoints/README.md — human-readable schema reference (nice to have; the schema

in this document is the authority).

1. package.json scripts / CI validation / .gitattributes merge driver — repo

ergonomics for a team that tracks many checkpoints. Optional.

1. Do _not_ wire a per-merge auto-stamp workflow. Earlier guidance here

recommended a .github/workflows/checkpoint-after-merge.yml that opened a stamp PR on every merge to main. opchain.dev shipped it and removed it 2026-06-22 because it was net-negative under branch protection — see Anti-pattern: don't auto-stamp `merged_prs` per merge under Write Protocol → Checkpoint Size. Let the assistant restamp oc-git-ops at inflection points instead.

Do not add .checkpoints/ to .gitignore. Tracking the directory in git is what makes checkpoints survive across sessions and machines — including ephemeral runners like Claude Code on the web.

/checkpoint Command

Any skill that adopts this protocol should recognize /checkpoint as a utility command. It is a prose convention, not a registered verb: no skill declares it in frontmatter and the plugin ships no command file for it, so a skill handles it when the user types it.

/checkpoint         Show current checkpoint status for active project
/checkpoint next    Show the single highest-priority next action (priority engine)
/checkpoint doctor  Cross-check checkpoints against git + filesystem for drift
/checkpoint show    Display full checkpoint contents
/checkpoint reset   Archive current checkpoint and start fresh
/checkpoint list    List all checkpoints in the project directory

This is a cross-skill command — any checkpoint-aware skill handles it the same way. The behavior is identical regardless of which skill the user is currently in.

Directory Convention

project-dir/
├── .checkpoints/
│   ├── oc-app-architect.checkpoint.json
│   ├── oc-code-auditor.checkpoint.json
│   ├── oc-reverse-spec.checkpoint.json
│   └── oc-deploy-ops.checkpoint.json
├── spec/           (oc-app-architect output)
├── sprints/        (oc-app-architect Phase 6 build loop output)
├── src/            (project source)
└── ...

The .checkpoints/ directory is:

• Tracked in git (was gitignored in v1.0; flipped to tracked because

Claude Code on the web has an ephemeral worker — gitignored state doesn't survive sessions). Treat checkpoints as living "session state docs" the team can read in PRs alongside the code change.

• Readable by any skill in the ecosystem
• Validated by CI via npm run checkpoint:validate (see

.checkpoints/README.md and scripts/checkpoint.mjs for the schema and tooling)

• Surfaced via npm run checkpoint:status — the canonical "where did I

leave off?" command for new sessions

Local MCP also maintains .checkpoints/.gitignore entries for its private runtime artifacts: .mcp-sessions.json, *.lock, .*.tmp, and the reserved .local/ subtree. Skill *.checkpoint.json files remain trackable.

Optional extension: pm_refs

pm_refs is an optional, additive field (introduced in skill release 1.2) under on-disk schema 1.0 — checkpoints without it stay valid. It lets a skill's checkpoint carry the PM tickets it touched so downstream skills find context without re-asking.

Status: the field is fully specified and validated when present (see Validation below), but in practice skills today still record PM refs ad-hoc in skill_state (e.g. linear_active_parents). Prefer pm_refs for anything a sibling skill needs to read; keep skill-private PM bookkeeping in skill_state.

Field shape

{
  // ...existing fields
  "pm_refs": [
    {
      "provider": "linear",                  // or "jira" | "github-issues"
      "id": "PLAT-4471",                     // ticket id
      "url": "https://linear.app/onramp/issue/PLAT-4471",
      "role": "source",                      // "source" | "child" | "deploy" | "incident" | "linked"
      "created_by_skill": "oc-app-architect",   // which skill linked it
      "first_seen_at": "2026-05-04T12:00:00Z"
    }
  ]
}

role semantics:

• source — the originating ticket (one per checkpoint, typically).
• child — sprint / step / sub-ticket created by this skill.
• deploy — deploy-ops-created deploy ticket.
• incident — monitoring-ops-created incident ticket.
• linked — a related ticket the skill referenced but didn't author.

Read pattern (downstream skills)

When any skill starts, after reading its own checkpoint, it also reads `pm_refs` from sibling-skill checkpoints to find context. Example: oc-git-ops, on /oc-git-sync with no explicit ticket id, looks at oc-app-architect.checkpoint.json#pm_refs to find the source ticket from the most recent build phase.

Write pattern

Every skill that touches a PM ticket appends to its own pm_refs array at the same time it writes the ticket. The array is append-only within a session; entries are not deduplicated across sessions (the audit trail is per-session).

Deferred PM writes

Skills that follow oc-integrations-engineer's PM-MCP protocol (references/pm-mcp-protocol.md in that skill) may also write pm_deferred_actions, pm_flush_log and pm_idempotent_skips beside pm_refs. They are optional, shaped by that protocol, and the validator does not check them.

Status surface

npm run checkpoint:status does not render pm_refs. To follow a ticket across skills at resume, read each checkpoint's pm_refs directly (node scripts/checkpoint.mjs show <skill>, or open the JSON).

Validation

npm run checkpoint:validate treats pm_refs as optional, but when it is present it checks the shape: each entry needs a provider and id, and any role must be one of source|child|deploy|incident|linked. Checkpoints without the field validate unchanged. There is no batch migration — the field appears on a skill's next write.

Privacy in regulated environments

The pm_refs array stores ticket ids + URLs. It does not store ticket bodies. Tickets in regulated environments may contain CUI / PHI; the body retrieval path runs through the broker + redactor on each access. The checkpoint is therefore safe to commit + share within the project.

Wire 1.1 extensions: cost, eval_scores, telemetry_handle

Three optional, additive fields introduced with on-disk schema "1.1" (v1.6 "the instrumented pipeline"). Checkpoints without them stay valid; they are validated only when present. Together they make the pipeline instrumented: every phase can report cost, every skill can report an eval score, every checkpoint can carry a budget and an opt-in telemetry link.

cost — LLM spend attribution + budget gate (owner: oc-cost-ops)

{
  "cost": {
    "currency": "USD",                       // optional, default USD
    "total_usd": 12.34,                      // optional, ≥ 0 — spend attributed to this checkpoint
    "budget_usd": 50,                        // optional, ≥ 0 — the budget ceiling; gate trips when total > budget
    "by_phase": { "spec": 3.10, "build": 8.40, "audit": 0.84 },   // optional, name → ≥ 0
    "by_model": { "claude-opus-4-8": 9.2, "claude-haiku-4-5": 3.1 }, // optional, name → ≥ 0
    "tokens": { "input": 1_200_000, "output": 240_000 },          // optional, free-form
    "updated_at": "2026-06-25T12:00:00Z"     // optional
  }
}

oc-cost-ops owns this field. The validator enforces: cost is an object; total_usd/budget_usd are non-negative numbers; by_phase/by_model map names to non-negative numbers. When total_usd > budget_usd > 0 the validator warns ("budget gate tripped") rather than erroring — overspend is a signal, not a corrupt file. The budget gate (block vs warn) is policy oc-cost-ops applies; the checkpoint just records the numbers.

eval_scores — scores against a stable rubric (owners: oc-bug-check, oc-code-auditor, oc-prompt-ops)

{
  "eval_scores": [
    { "rubric": "oc-code-auditor", "score": 8.2, "max": 10, "at": "2026-06-25T12:00:00Z",
      "ref": "sprints/sprint-2/eval-round-1.md",
      "dimensions": { "functionality": 9, "completeness": 8, "quality": 8, "ux": 8 } },
    { "rubric": "oc-prompt-ops", "score": 0.93, "max": 1 }   // 0..1 pass_rate uses max: 1
  ]
}

Append-only list. The score is rubric-relative — pair it with max when the scale isn't 0..10 (a prompt-ops pass_rate is 0..1 with max: 1; a code-auditor grade is 0..10). The validator requires each entry to be an object with a string rubric and a numeric score; max (if present) must be positive and score must not exceed it; at (if present) must be ISO-8601; dimensions (if present) maps names to numbers. This is what lets oc-orchestrator and oc-cost-ops reason about quality trend, not just pass/fail.

telemetry_handle — opt-in local-metering link (owner: oc-telemetry-ops)

{
  // a bare anonymous id …
  "telemetry_handle": "anon-7f3a91c0"
  // … or the richer opt-in object form:
  // "telemetry_handle": { "enabled": true, "id": "anon-7f3a91c0",
  //                       "sink": ".checkpoints/usage.sqlite",
  //                       "since": "2026-06-25T12:00:00Z" }
}

Links a checkpoint to its rows in the local usage.sqlite metering store without storing any PII or content. Default stance is OFF — the field's presence never grants consent, including a copied enabled: true value. Only local SQLite metadata written by an explicit telemetry enable operation grants permission on this machine. A string is an anonymous handle; the legacy object may carry historical status, sink path and start time. Neither form enables tracking in a clone. The validator accepts a non-empty string or an object whose enabled (when present) is boolean, id/sink are strings, and since is ISO-8601. oc-telemetry-ops owns the metering store and the consent gate; the checkpoint only carries the link.

Validation & migration

npm run checkpoint:validate treats all three as optional and checks their shape only when present (exactly like pm_refs). Existing "1.0" checkpoints validate unchanged. The forward sweep ("1.0" → "1.1" stamp) is an oc-migration-ops job — additive, no data transform, reversible — the same way governance frontmatter rolled out in v1.4.

Principles

1. Read the checkpoint, not the chat history. Chat history is gone next session.

The checkpoint is the only truth that survives.

1. Write often, write small. Every completed step gets a checkpoint update.

The cost of writing is negligible; the cost of losing progress is a full session.

1. Context primer > full re-read. A good context primer means the new session

never needs to re-read the entire codebase or all generated files. 20 lines of dense summary beats 200 lines of re-analysis.

1. JSON for machines, summaries for humans. The checkpoint is JSON so skills can

parse it. The progress_summary and next_actions are human-readable so the user can understand what's happening.

1. Private state stays private. skill_state is an opaque bag the protocol doesn't

define; other skills read only the keys its owner documents for them.

1. Never block on a missing checkpoint. If the checkpoint is corrupt, missing, or

from an incompatible version, the skill starts fresh and tells the user why.