From b405fff94d6ddcdd5b2278f20c327c583aad487d Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Thu, 11 Jun 2026 19:53:38 -0500 Subject: docs(spec): data-integrity rules for helper instances MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four loss windows the scoped-edit discipline doesn't cover: a primary file-wide hygiene pass silently clobbering a helper's concurrent edit (gate on live session-context.d/ files before any such pass), a new primary misreading helper dirt as leftover mess (surface live helper files at startup), crash recovery for shared-file edits (helpers journal each edit before applying it), and MEMORY.md's anchor-less read-modify-write index (memory writes stay primary-only). Backstop: every file-wide pass snapshots to /tmp before modifying. lint-org and wrap-org-table already conform; todo-cleanup — the pass that moves whole subtrees — does not, and Phase 1.5 brings it up to the invariant. --- todo.org | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'todo.org') diff --git a/todo.org b/todo.org index bb1c2cb..caabb7e 100644 --- a/todo.org +++ b/todo.org @@ -50,7 +50,8 @@ Implement Phase 1.5 of the generic-agent-runtime spec ([[file:docs/design/2026-0 - =ai --helper= flag: live-anchor detection, auto AI_AGENT_ID + AI_HELPER export, tmux window naming, warn-and-run-normal when no primary is live. - Shared-file read/write contract into protocols.org (helper: scoped single-heading org edits only; file-wide passes, inbox processing, and all git mutation stay primary-only); helper branches in startup.org (light path, no pulls/rsync) and wrap-it-up.org (archive own file, skip hygiene + commit). - Bats: launcher id assignment/sanitization, helper-vs-primary resolution, two simultaneous context files. -- Manual validation with Craig: live helper against a live primary — lookup, one scoped todo.org edit, wrap-up, primary commits the helper's edit cleanly. +- Data-integrity items (spec second pass, 2026-06-11): live-helper gate before any file-wide hygiene pass (todo-cleanup/lint-org/wrap-org-table check session-context.d/, pause + ask on live files, surface stale ones); todo-cleanup.el brought up to the backup-to-/tmp invariant (lint-org and wrap-org-table already conform — verified); log-before-write journaling for helper shared-file edits; memory writes primary-only (MEMORY.md has no heading anchors — helpers log candidates instead); agent id in helper-originated inbox-send slugs (minute-resolution filenames can collide). +- Manual validation with Craig: live helper against a live primary — lookup, one scoped todo.org edit, wrap-up, primary commits the helper's edit cleanly. Then the corruption drill: primary attempts wrap-up while the helper is mid-task and the hygiene gate visibly pauses. Independent of the spec's phases 2-6 (runtime-neutral refactor), which stay gated on their own go/no-go. -- cgit v1.2.3