Stage Snapshot Writer

Overview

Stage Snapshot Writer is the producer contract for per-task stage snapshots — introduced in v2.13.0 (TUNE-0254). Every /dr-* command, as its terminal step, persists the final operator-visible response (Summary + Gate Results + CTA block) to datarim/snapshots/{TASK-ID}.snapshot.md with overwrite semantics, an 8 KB hard cap and a mkdir-based atomic lock.

Why it exists

Before v2.13.0, /dr-next {TASK-ID} after /clear had to re-derive the next stage from cold artefacts — PRD, plan, task-description, activeContext. For an L3+ task with a 700-line plan, this consumes ~30% of the context window and loses key information about what the agent just did and which CTA options were emitted. The fix: a small, overwrite-on-retry snapshot file the consumer can read first.

Single producer touchpoint

The writer is invoked from a single place — skills/cta-format.md § Snapshot Emission. Because cta-format.md is already mandatory at the end of every /dr-* command response, adding the snapshot step to one skill covers all 15+ producer commands without N-touchpoint patches.

Snapshot file shape

---
task_id: TUNE-0254
artifact: stage-snapshot
schema_version: 1
stage: plan
command: /dr-plan
captured_at: 2026-05-21T13:45:00Z
captured_by: agent
recommended_next: /dr-do
options:
  - "/dr-do TUNE-0254 | implementation"
  - "/dr-status | escape hatch"
size_bytes: 6432
truncated: false
---

<rendered Summary + Gate Results + CTA block; total file ≤ 8192 bytes>

Safety controls

• TASK-ID regex — ^[A-Z][A-Z0-9-]+-[0-9]{4,5}$; rejects path-traversal attempts before any file IO.
• mkdir-based atomic lock — reuses scripts/lib/plugin-system.sh::acquire_plugin_lock() (macOS-portable, no flock dependency); default 60 s timeout via DR_SNAPSHOT_LOCK_TIMEOUT.
• Write-temp-rename — body written to a .tmp file and mv-renamed; atomic on POSIX.
• chmod 600 — snapshot files are readable only by the running user; lock dir chmod 700.
• Hard size cap — 8192 bytes per file total; overflow body is truncated with marker <!-- snapshot-truncated, full ответ см. session jsonl -->.
• Kill switch — DATARIM_DISABLE_SNAPSHOT=1 makes the writer a no-op.

Consumer side

Snapshot is consumed by /dr-next (Step 2.5 «Snapshot-First Read») and /dr-orchestrate (Snapshot-First Resume) via the sibling skill dr-next-snapshot-replay.md. Cleanup at /dr-archive Step 0.95 moves the final snapshot to documentation/archive/<subdir>/snapshots/{TASK-ID}-final-stage.md — move, not delete.

Source

TUNE-0254, v2.13.0, 2026-05-21. PRD: datarim/prd/PRD-TUNE-0254-stage-snapshot.md. Implementation: scripts/lib/snapshot-writer.sh. Tests: 44 bats cases across 10 suites (writer overwrite, frontmatter schema, size cap, flock race, cta-format integration, cleanup-on-archive, dr-archive subdir resolution).