aboutsummaryrefslogtreecommitdiff
path: root/.ai/workflows/monitor-inbox.org
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-06-15 10:36:22 -0500
committerCraig Jennings <c@cjennings.net>2026-06-15 10:36:22 -0500
commitedb545db727861f21052ca5111db1d949ebf030a (patch)
treee397b11aaa8ff75e365dad745b79967817678afd /.ai/workflows/monitor-inbox.org
parent5e746fb0379c8873fd8277242791f931d4cf9198 (diff)
downloadrulesets-edb545db727861f21052ca5111db1d949ebf030a.tar.gz
rulesets-edb545db727861f21052ca5111db1d949ebf030a.zip
feat(inbox): define monitor-inbox as a 15-min loop with clean-tree gates
Redefine "monitor the inbox" as the explicit behavior Craig wants: run one process-inbox pass now, then loop process-inbox every 15 minutes. The 15-minute loop was previously an opt-in background recipe; it's now the defined meaning of the phrase. Gate the workflow at both ends on a clean worktree and a green full-suite run. Starting on a dirty tree lets the per-item auto-commit sweep up unrelated changes; starting on a red suite hides whether the monitor broke anything. On a dirty tree, offer to commit in discrete batches; on a red suite, offer to investigate — never start until both are satisfied, and leave the tree clean and green when the loop stops. Add the no-approvals execute criteria: an accepted item self-applies only when agreed (passed the value gate and Skeptical Review), quick (under ~15 min including verification), and solo (no decision needed from Craig). All three commit and push at the end of the item; miss any and it files or, for shared-asset and convention changes, parks. Broaden the Skeptical Review to run on every arriving task and file, not only shared-asset proposals — a core right/complete/simpler pass on everything, with the cross-project battery added for changes that sync to consuming projects.
Diffstat (limited to '.ai/workflows/monitor-inbox.org')
-rw-r--r--.ai/workflows/monitor-inbox.org52
1 files changed, 40 insertions, 12 deletions
diff --git a/.ai/workflows/monitor-inbox.org b/.ai/workflows/monitor-inbox.org
index 1639f3b..4912a2b 100644
--- a/.ai/workflows/monitor-inbox.org
+++ b/.ai/workflows/monitor-inbox.org
@@ -8,18 +8,35 @@ Keep the project's =inbox/= responsive: notice handoffs on a cadence, triage eac
The gap this closes: handoffs that arrive mid-session used to sit unseen until the user asked or the next startup ran. A handoff the sender can't see being handled trains them to escalate around the inbox channel.
+* Preconditions — before starting
+
+Never begin inbox monitoring on a dirty worktree or with a failing test suite. A dirty tree means the auto-commit at the end of an executed item sweeps up unrelated changes; a red suite means you can't tell whether the monitor broke something. At the start of the workflow, check both:
+
+1. =git status --porcelain= is empty (clean worktree).
+2. A full test run is all green (=make test= here, or the project's full-suite command).
+
+If the worktree is *dirty*: offer to commit the pending changes in discrete, logical batches before starting. If the suite is *red*: offer to investigate the failures first. Surface the blocker with inline numbered options per =interaction.md= and wait — monitoring does not start until the tree is clean and the suite is green.
+
* When to Use This Workflow
Trigger phrases:
-- "monitor the inbox" / "watch the inbox"
-- "respond to the handoffs" / "handle the handoffs"
+- "monitor the inbox" / "watch the inbox" — *the defined meaning:* run one process-inbox pass now, then loop process-inbox every 15 minutes (see Cadence). Not an opt-in extra — the phrase *is* the loop.
+- "respond to the handoffs" / "handle the handoffs" — a single pass now, no loop.
-Cadence auto-trigger (the main mechanism — see Cadence below): check at every task boundary during a session, not only when asked.
+Cadence auto-trigger (ambient, always on): check at every task boundary during a session, even when no loop is running — see Cadence below.
* Cadence — how often to check
-*Default: check at every task boundary.* After finishing a unit of work, before reporting back or asking "what's next," run the cheap status check:
+*"Monitor the inbox" = run now, then loop every 15 minutes.* When Craig says monitor or watch the inbox, do one process-inbox pass over any pending handoffs immediately, then start the loop:
+
+#+begin_src
+/loop 15m check the inbox with inbox-status and run process-inbox.org over any pending handoffs
+#+end_src
+
+Each firing runs the cheap =inbox-status= check first and only does a full process-inbox pass when items are pending. The loop is the monitoring; it runs until Craig stops it or the session ends. Honor the Preconditions gate before the first pass and the Close-out gate when the loop stops.
+
+*Ambient task-boundary check (always on, even without a loop).* After finishing a unit of work, before reporting back or asking "what's next," run the cheap status check:
#+begin_src bash
.ai/scripts/inbox-status -q
@@ -31,14 +48,6 @@ Exit 1 means handoffs are pending — list them (drop =-q=) and process per proc
*Mid-task arrivals.* If a handoff lands while you're mid-task and it's urgent (blocks the current work, or is time-sensitive), surface it right away. Otherwise batch it to the next task boundary so the current work isn't thrashed.
-*Unattended / background monitoring (opt-in).* When the user is working elsewhere and wants rulesets handoffs handled without being present, run a polling loop:
-
-#+begin_src
-/loop 15m check the inbox with inbox-status and process any handoffs per process-inbox.org
-#+end_src
-
-This is opt-in, not the default — continuous polling has a cost, and most handoffs aren't urgent. Pick an interval matched to how fast handoffs actually arrive (a burst of cross-project work warrants a tighter loop; a quiet day warrants none).
-
* The act-vs-file decision
Every accepted handoff (one that clears process-inbox's value gate) is then either acted on now or filed as a task. The rule, and how to surface it:
@@ -75,6 +84,16 @@ Pick a number.
*Always ask if you're unsure* which side of the line an item falls on. Decisiveness on clear act-now items is the point of the rule; the ask is for genuine ambiguity and for filing.
+** Executing in no-approvals mode
+
+When Craig has put the session in no-approvals mode, an accepted item may be implemented automatically — but only when all three of these hold:
+
+1. *Agreed* — you've run the value gate and the full Skeptical Review and concluded the change should be done, not merely that it's harmless.
+2. *Quick* — the whole implementation, including verification, is under ~15 minutes.
+3. *Solo* — you can carry it end to end without a decision from Craig. Manual verification you perform yourself is fine; needing Craig to choose an option, approve a design, or resolve an ambiguity is not.
+
+All three → implement it, verify, then commit and push at the end of that item (the Step 0 reconcile and pre-push check from =commits.md= still run). Miss any one and it doesn't self-apply: a shared-asset or convention change needs Craig's decision, so it fails *solo* and routes to process-inbox's defer-and-stage park; an oversized item fails *quick* and gets filed.
+
* Replying to handoffs
A handoff came from another project's agent (or the user). Close the loop:
@@ -89,6 +108,15 @@ Cross-project boundary: never act on a file under another project's =.ai/= scope
=.ai/scripts/inbox-status= lists unprocessed handoffs and exits nonzero when any are pending. Exclusions match the wrap-up sanity check (=.gitkeep=, =lint-followups.org=, =PROCESSED-*=). Exit 0 = clean, 1 = pending, 2 = no inbox/ or bad usage. Use =-q= for the count-only form the cadence check calls.
+* Close out — before finishing
+
+End the workflow the way it started: clean worktree, green suite. Before stopping the loop or reporting the pass done:
+
+1. Commit or revert everything left in the worktree — nothing uncommitted remains.
+2. Run the full test suite once more and confirm all green.
+
+If either can't be satisfied — a half-done item, a failure introduced during the pass — surface it rather than leaving it. The next monitor run assumes a clean, green starting state (the Preconditions gate), so handing it a dirty tree or a red suite breaks the next run before it begins.
+
* Living Document
Tune the cadence if task-boundary checking proves too frequent or too sparse in practice. Refine the act-vs-file criteria as edge cases recur. If the background-monitor loop becomes a common pattern, capture the interval that worked. The decision rule itself — act-now is silent, filing asks with file-as-option-1, ambiguity asks — is the stable core (set by Craig, 2026-05-30).