D
Datarim
EN RU
Скилл Core

Stage Snapshot Writer

Producer-контракт для per-task снапшотов стадии — финальный operator-visible /dr-* ответ сохраняется в datarim/snapshots/{TASK-ID}.snapshot.md с перезаписью. Единственная producer-точка через cta-format.md.

Обзор

Stage Snapshot Writer — producer-контракт для per-task снапшотов стадии, введён в v2.13.0 (TUNE-0254). Каждая /dr-* команда как терминальный шаг сохраняет финальный operator-visible ответ (Summary + Gate Results + CTA-блок) в datarim/snapshots/{TASK-ID}.snapshot.md с семантикой overwrite, hard cap 8 КБ и mkdir-based atomic lock.

Зачем это нужно

До v2.13.0 команда /dr-next {TASK-ID} после /clear заново выводила следующую стадию из холодных артефактов — PRD, plan, task-description, activeContext. Для L3+ задачи с планом на 700 строк это съедало ~30% контекст-окна и теряло ключевую информацию: что агент только что сделал, какие CTA-опции эмитированы. Решение — маленький overwrite-on-retry файл, который consumer читает первым.

Единственная producer-точка

Writer вызывается из единственного места — skills/cta-format.md § Snapshot Emission. Поскольку cta-format.md уже обязательна в конце ответа каждой /dr-* команды, добавление снапшот-шага в один скил покрывает все 15+ producer-команд без N-точечных патчей.

Форма файла снапшота

---
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
---

<собранный Summary + Gate Results + CTA-блок; файл целиком ≤ 8192 байт>

Защитные контроли

  • TASK-ID regex — ^[A-Z][A-Z0-9-]+-[0-9]{4,5}$; отклоняет path-traversal до любого IO.
  • mkdir-based atomic lock — переиспользует scripts/lib/plugin-system.sh::acquire_plugin_lock() (macOS-portable, не требует flock); таймаут 60 с по умолчанию через DR_SNAPSHOT_LOCK_TIMEOUT.
  • Write-temp-rename — тело пишется в .tmp и атомарно переименовывается через mv (атомарно на POSIX).
  • chmod 600 — снапшот читается только запущенным пользователем; lock-каталог chmod 700.
  • Жёсткий size cap — 8192 байта на файл; превышение → marker <!-- snapshot-truncated, full ответ см. session jsonl -->.
  • Kill switch — DATARIM_DISABLE_SNAPSHOT=1 делает writer no-op.

Consumer-сторона

Снапшот читается командами /dr-next (Step 2.5 «Snapshot-First Read») и /dr-orchestrate (Snapshot-First Resume) через скил-сиблинг dr-next-snapshot-replay.md. Очистка на /dr-archive Step 0.95 переносит финальный снапшот в documentation/archive/<subdir>/snapshots/{TASK-ID}-final-stage.md — move, не delete.

Источник

TUNE-0254, v2.13.0, 2026-05-21. PRD: datarim/prd/PRD-TUNE-0254-stage-snapshot.md. Реализация: scripts/lib/snapshot-writer.sh. Тесты: 44 bats-кейса в 10 suites (writer overwrite, frontmatter schema, size cap, flock race, cta-format integration, cleanup-on-archive, dr-archive subdir resolution).

← Все возможности