1 files changed, 150 insertions, 0 deletions
diff --git a/docs/design/2026-07-14-sentry-workflow-proposal.org b/docs/design/2026-07-14-sentry-workflow-proposal.org
new file mode 100644
index 0000000..d29ceb8
--- /dev/null
+++ b/docs/design/2026-07-14-sentry-workflow-proposal.org
@@ -0,0 +1,150 @@
+#+TITLE: Sentry Workflow — Proposal for rulesets
+#+AUTHOR: Craig Jennings
+#+DATE: 2026-07-13
+
+* Status
+Proposal from the work project to the rulesets session, for implementation as a
+general (shared-layer) workflow: =.ai/workflows/sentry.org= plus a small
+supporting script or two under =.ai/scripts/=.
+
+* Problem
+
+An agent session left running overnight can keep a project clean and healthy on
+a cadence, but the current pieces don't coordinate. Two gaps:
+
+1. *No agent-vs-agent collision guard on shared public files.* =capture-guard=
+   only detects Emacs org-capture buffers (the human case) on one target file,
+   and it's advisory, not a lock. There is no flock anywhere in =.ai/scripts/=.
+   Multiple sessions (several projects, sometimes both daily drivers) can
+   read-modify-write =~/org/roam/inbox.org= and the =agents/= KB nodes at once.
+   The only coordination is the git pull/commit/push discipline in
+   knowledge-base.md, which is optimistic — a pull/push race forks a
+   =*sync-conflict*= file, and the KB search already globs those out, so we know
+   the forks happen and get dropped.
+
+2. *No single serialized runner.* Firing inbox-zero and triage-intake as
+   separate hourly crons means they can overlap each other and other agents.
+
+Sentry is one supervisor loop that runs a fixed sequence of hygiene passes
+serially, holds locks so it never collides with itself or other agents, and
+checkpoints aggressively for crash recovery.
+
+* What sentry is
+
+A single workflow, driven by one interactive =/loop= (one cron), that on each
+fire walks an ordered list of passes inside a single turn. It replaces the
+per-task crons. Design invariants:
+
+- *Serial.* Passes run one at a time, in order. They never overlap each other.
+- *Single-runner lock.* Sentry takes a project-local flock
+  (=.ai/.sentry.lock=) at entry. If a prior fire is still running, this fire
+  skips instead of doubling up.
+- *Shared-file lock.* Any pass that writes a public roam file first acquires a
+  roam-write lock (flock on =~/org/roam/.roam-write.lock=) held across the whole
+  read-modify-write-commit-push cycle, so it serializes against other agents on
+  the same host. =capture-guard= still runs underneath for the human case. (The
+  roam-write lock is new; it's the general guard the dropped KB-guard note would
+  have proposed, folded in here.)
+- *Non-destructive by default.* Read-only and idempotent-filing passes run
+  fully. Anything destructive or judgment-heavy (triage trash/mark-read, task
+  regrades, spec flips) queues its proposal into the digest for morning
+  approval, never fires unattended.
+- *Idempotent + isolated.* Every pass is safe to repeat. A pass that errors
+  doesn't abort the rest; its failure is a loud banner in the digest.
+
+* Crash-recovery spine (applies to every pass)
+
+Crash recovery has been a live consideration. Two enforced steps wrap each pass:
+
+1. *Session-context between passes.* Before the next pass starts, the current
+   pass appends a dated entry to =.ai/session-context.org= recording what it
+   did. A crash mid-sequence leaves a readable "got this far" trail, so the next
+   session resumes without re-deriving state.
+2. *Local commit, no push, on any disk change.* Every pass that writes to disk
+   gets its own =chore(sentry): <pass> — <what changed>= commit on the current
+   branch, unpushed. A crash loses at most one pass. Craig reviews the stack in
+   the morning and pushes deliberately. Conventional messages, no AI
+   attribution. (Open decision: commit on the current branch vs a dedicated
+   =sentry/<date>= branch — see Open decisions.)
+
+The unit per pass is therefore: do the work → log to session-context → commit.
+That triplet is the recovery boundary.
+
+* Passes (v1 — all ten, plus the first-run KB promotion)
+
+Ordered so read-only/pull passes precede writes, and the heaviest external
+sweep sits mid-run:
+
+1. *Roam pull* — =git -C ~/org/roam pull --ff-only= so later reads are fresh.
+   Read-only.
+2. *Inbox zero* — inbox.org roam mode. Route roam-inbox items this project
+   owns. Acquires the roam-write lock for the inbox edit.
+3. *Triage intake* — triage-intake.org. External-accounts sweep, classify,
+   file Action tasks. Destructive actions (trash/mark-read) queue for morning;
+   =mbsync -a= and the sentinel advance run.
+4. *Todo cleanup* — clean-todo.org + todo-cleanup.el + lint-org.el. Convert
+   level-3 done subtasks to dated logs, archive done subtrees, flag lint.
+5. *Task audit* — task-audit.org. Re-check =:solo:=/=:quick:= tags,
+   priority-scheme conformance, bug severity×frequency grades, stale =DOING=
+   specs with closed parents, blocked/blocker reciprocity. Regrades queue for
+   morning.
+6. *Working-files hygiene* — flag =working/<slug>/= dirs whose task is DONE but
+   not filed to =assets/=. Report only; filing is a morning decision.
+7. *Spec status board* — the docs-lifecycle grep. Flag =DOING= specs with
+   closed parents, or specs stuck in =DRAFT=.
+8. *Link integrity* — lint-org broken =file:= links across todo/notes/prep.
+9. *Git health* — uncommitted drift, unpushed commits, stale local branches,
+   whether main is behind origin.
+10. *Prep + symlink freshness* — verify tomorrow's prep and both symlinks
+    resolve.
+11. *KB lesson promotion (first run of the session, and thereafter as new
+    lessons accrue)* — promote recent durable lessons out of the fast capture
+    layer. CLASSIFICATION-GATED:
+    - Personal project → write to the roam KB as =agents/= nodes (pull, lock,
+      write, commit, push), per knowledge-base.md.
+    - Work / denylisted project → NEVER touch roam. Promote to the project's own
+      durable store (e.g. =deepsat/knowledge.org=) instead, and emit the
+      one-line refusal note from the knowledge-base.md refusal contract so
+      nothing is lost silently.
+
+* Digest output
+
+One consolidated, timestamped summary per fire: run time first, then per-pass
+one-liners (what it found / did), the morning-approval queue (proposed
+trash/mark-read, regrades, files-to-move), and any failures as loud banners at
+the top. Delta-only where a pass supports it (triage): a pass with nothing to
+report is one line.
+
+* Cadence
+
+One hourly sentry to start (passes short-circuit fast when there's nothing to
+do). A slower evening interval (every 2–3 hours) is a config knob if hourly
+proves noisy.
+
+* Open decisions for rulesets
+
+1. *Commit target* — per-pass commits on the current branch (simplest, matches
+   "commit but don't push") vs a dedicated =sentry/<date>= branch (keeps the
+   working branch clean, costs a branch dance). Proposal leans current branch.
+2. *Roam-write lock scope* — host-local flock only (solves same-host
+   multi-agent, the common case) vs also hardening roam-sync to surface
+   cross-host conflicts loudly. Proposal: ship the flock now, note the
+   cross-host limit, treat roam-sync conflict-surfacing as a separate follow-up.
+3. *Interval default* — hourly vs evening-only. Proposal: hourly, config knob.
+4. *Which passes gate on a green tree* — e.g. skip todo-cleanup commits if the
+   project suite is red, matching inbox monitor-mode's clean-tree gate.
+
+* Cover note from sender (work, 2026-07-14 00:02)
+
+Intro for the sentry-proposal.org file just sent. This is a NEW general workflow proposal (.ai/workflows/sentry.org + supporting scripts under .ai/scripts/), not an edit to an existing synced file.
+
+What it is: one serialized supervisor loop that runs a project's evening hygiene passes on a cadence, with locks so it never collides with itself or with other agents. It replaces firing inbox-zero + triage-intake as separate crons.
+
+Why now: an agent left running overnight can keep a project clean, but the current pieces don't coordinate. capture-guard only handles the Emacs-capture case on one file and holds no lock; there is no flock anywhere in .ai/scripts/; and separate crons let inbox-zero and triage overlap each other and other agents on shared roam files, which already fork *sync-conflict* files that the KB search globs out.
+
+Three design points worth your judgment:
+1. Crash-recovery spine on every pass (crash recovery has been a live concern): enforce a session-context.org update BETWEEN passes, and a local commit (no push) after any disk change, so a crash loses at most one pass.
+2. A new roam-write flock (~/org/roam/.roam-write.lock) as the shared-file guard. This absorbs a separate 'guard all public KB files' note we considered and dropped. The lock is the better home for that concern than a bespoke per-file guard.
+3. The KB lesson-promotion pass is classification-gated: personal projects promote to roam agents/ nodes; a denylisted work project promotes to its own local store (deepsat/knowledge.org) and never touches roam, per knowledge-base.md's refusal contract.
+
+Companion files to reconcile: knowledge-base.md (the gated promotion + refusal contract), inbox.org (roam mode + the new lock), triage-intake.org (runs as a sentry pass; keep its own triggers), capture-guard (becomes one layer under the roam-write lock, not the whole guard), and clean-todo.org / task-audit.org / lint-org.el (invoked as passes). Open decisions for you are listed at the bottom of the proposal file: commit target, lock scope, interval default, and which passes gate on a green tree.