diff options
66 files changed, 5298 insertions, 1542 deletions
diff --git a/.ai/notes.org b/.ai/notes.org index 447c33c..b6c85f8 100644 --- a/.ai/notes.org +++ b/.ai/notes.org @@ -61,6 +61,8 @@ This section tracks decisions that need Craig's input before work can proceed. ** Current Reminders +- =[2026-07-27]= Finish the context-engineering rightsizing — Craig's explicit ask at wrap. Surface is 57,800 → 28,949 tokens; the remaining work needs *his decisions*, not execution: =verification.md= (C1 — its honesty core vs the Opus 5 over-verification warning), =interaction.md= (3,828 tok, largest remaining), the TDD rationalization table (cut or keep), and D3 the gate separation (which approval gates are preference vs guardrail). Task: "Finish context-engineering rightsizing" in todo.org. Docs in =working/context-engineering-rightsizing/= are one commit behind — reconcile them first. + - =[2026-07-14]= Review the sentry spec (docs/specs/2026-07-14-sentry-workflow-spec.org) — Craig's explicit ask at wrap: strongly suggest he reviews it before ending the next session. All 12 review findings and 10 decisions are resolved and folded in; the spec is open in his Emacs; the READY flip and the [#B] build task both wait on his deep read. ** Instructions for This Section @@ -83,6 +85,6 @@ Format: Markers maintained by workflows to record when they last ran. Read by other workflows that gate their behavior on freshness. :LAST_AUDIT: 2026-07-20 (open set current — this session's shipped work (working/temp, triage-source-activation, silent-until-signal, suspend detach) closed as it went; sentry cluster consolidated (merged the /schedule tasks, added cross-host-coordination); nothing shipped-but-open per git reconcile. Live finding: the Polyglot + Subprojects scouting tasks are SCHEDULED 2026-07-20 and due.) -:LAST_INBOX_PROCESS: 2026-07-25 (consolidated home + work Claude-to-Codex MCP registry proposals into one [#B] parked spec decision; memory auditor split from the registry work) +:LAST_INBOX_PROCESS: 2026-07-31 (four work handoffs: standup-scripts proposal accepted with four changes and shipped as a212eeb; voice pattern #48 filed [#B], then its interaction.md mirror folded in on Craig's approval; a correction FYI acknowledged — my project-workflows fork claim was wrong, Phase 11 composes rather than shadows) Format: one =:MARKER: YYYY-MM-DD= line per workflow. Workflows overwrite their own marker on completion. diff --git a/.ai/protocols.org b/.ai/protocols.org index f4eefed..b291d9e 100644 --- a/.ai/protocols.org +++ b/.ai/protocols.org @@ -106,7 +106,7 @@ The epoch is baked into the id by the spawner, never minted inside =session-cont Resolve the path with =.ai/scripts/session-context-path= rather than hardcoding =.ai/session-context.org=; it prints the right path for the current =AI_AGENT_ID=. Fall back to =.ai/session-context.org= if the script isn't present (older checkouts mid-sync). Everything below — the record/recovery purpose, the update triggers, the startup existence check, the wrap-up rename — operates on that resolved path. The prose says "session-context.org" as the default name; read it as "the resolved active path" when =AI_AGENT_ID= is set. -A helper instance (a second agent running in this project while a primary session is live) follows a different contract: it skips the pulls and rsync, makes only scoped single-heading edits to shared files, leaves all git mutation to the primary, and wraps up by archiving its own context file without committing. The full rules — read/write tiers, data-integrity, light startup, helper wrap-up — live in [[file:workflows/helper-mode.org][workflows/helper-mode.org]]. A session is a helper only when something routes it there (the =ai --helper= launcher, startup's roster check, or an explicit "you are a helper" instruction); the routing itself ships behind the helper-instance feature gate and isn't live yet. +A helper instance (a second agent running in this project while a primary session is live) follows a different contract: it skips the pulls and rsync, makes only scoped single-heading edits to shared files, leaves all git mutation to the primary, and wraps up by archiving its own context file without committing. The full rules — read/write tiers, data-integrity, light startup, helper wrap-up — live in [[file:workflows/helper-mode.org][workflows/helper-mode.org]]. A session is a helper only when something routes it there: the =ai --helper= launcher (live — it checks the roster, assigns the id, and opens the helper in its own tmux window) or an explicit "you are a helper" instruction. Startup's roster check is *not* built, so a bare =claude= launched into a project that already has a live session will run full primary startup regardless. Launch helpers with =ai --helper=. This file serves two purposes with one mechanism: 1. *Crash recovery* — if the session dies mid-work, the live file is all that's left. On 2026-01-22 a session crashed during a 20-minute design discussion and all context was lost because this file wasn't being updated. @@ -270,7 +270,9 @@ The queue lives in the session anchor (=.ai/session-context.org=) under a =* Bef Three ways to access Craig's calendars: Google Calendar MCP (preferred, both personal + work accounts), gcalcli (fallback, personal only), Emacs org files (read-only viewer). -For tool recipes, authentication details, and credentials, see [[file:references/calendar-reference.org][calendar-reference.org]]. +For tool recipes and account details, read the calendar workflows in =.ai/workflows/=: =add-calendar-event.org=, =edit-calendar-event.org=, =delete-calendar-event.org=, =read-calendar-events.org=. They carry the MCP tool names, both account ids, the gcalcli fallback, and the conflict-check discipline. + +Credentials are needed only for a re-auth Craig performs himself. The MCP bundle's =mcp/README.org= in the rulesets repo is the authority: =gcp-oauth.keys.json= is gitignored and regenerated at install from a base64 var in the bundle, never committed. Named in prose rather than linked, because that path isn't synced into consuming projects. ** GPG Keys diff --git a/.ai/references/calendar-reference.org b/.ai/references/calendar-reference.org deleted file mode 100644 index 5791b08..0000000 --- a/.ai/references/calendar-reference.org +++ /dev/null @@ -1,66 +0,0 @@ -#+TITLE: Calendar Reference -#+AUTHOR: Craig Jennings - -Tool recipes, authentication, and credentials for Craig's calendar -setup. Three access methods, in order of preference. - -* Google Calendar MCP Server (preferred for all calendar operations) - -Craig has the =@cocal/google-calendar-mcp= MCP server configured at user scope (=~/.claude.json=). It provides full read/write access to Google Calendar via MCP tools. - -Two accounts are authenticated: -- *personal* — craigmartinjennings@gmail.com (primary: "Craig Google") -- *work* — craig.jennings@deepsat.com (primary: "Craig Deepsat") - -MCP tools available: -- =list-events=, =search-events=, =get-event= — read events -- =create-event=, =create-events= — add events -- =update-event= — modify events -- =delete-event= — remove events -- =list-calendars=, =list-colors= — calendar metadata -- =get-freebusy= — check availability -- =manage-accounts= — add/remove/list authenticated accounts -- =respond-to-event= — accept/decline invitations -- =get-current-time= — current time in any timezone - -Use =account_id: "personal"= or =account_id: "work"= to specify which account. - -Default calendar for adding events: "Craig Google" (personal account). - -Calendar workflows are available alongside this reference: add-calendar-event, edit-calendar-event, delete-calendar-event, read-calendar-events. - -If re-authentication is needed: -- Use the =manage-accounts= MCP tool with =action: "add"= and the account nickname -- OAuth credentials: =~/projects/homelab/assets/gcp-oauth.keys.json= -- Google Cloud app is in production mode (tokens don't expire after 7 days) -- See =~/projects/homelab/.ai/gcalcli-setup.org= for Google Cloud project details - -* gcalcli (fallback for personal account only) - -Craig has =gcalcli= installed via pipx, authenticated to his personal Google account only. - -#+begin_src bash -gcalcli agenda # upcoming events -gcalcli calw # weekly view -gcalcli add --title "..." --when "..." --duration "60" # add event -gcalcli search "..." # search events -gcalcli delete "..." # delete event -#+end_src - -Use =--calendar "Craig Google"= when adding events. - -gcalcli does NOT have access to the work (DeepSat) calendar. Use the MCP server for work calendar operations. - -If gcalcli needs re-authentication, credentials are stored in the homelab project: =~/projects/homelab/assets/gcalcli-client-secret.json.gpg= (GPG encrypted). - -* Emacs org files (read-only, for viewing schedules) - -Craig's calendars are at: =~/.emacs.d/data/*cal.org= (gcal.org, dcal.org, pcal.org) - -These files are **READ-ONLY** — NEVER add anything to them. - -Use this to: -- Check meeting times and schedules -- Verify when events occurred -- See what's upcoming -- Note: only updated periodically when Emacs is running — may be stale diff --git a/.ai/scripts/sync-templates b/.ai/scripts/sync-templates new file mode 100755 index 0000000..b9769f3 --- /dev/null +++ b/.ai/scripts/sync-templates @@ -0,0 +1,131 @@ +#!/usr/bin/env bash +# sync-templates — copy rulesets' canonical .ai/ templates into this project. +# +# Extracted verbatim from startup.org Phase A step 3 (2026-07-31). This is the +# mechanism that distributes every workflow, protocol and script change to every +# project, and until the extraction it was untested inline bash running in every +# session. The extraction exists so the guard changes that follow can be tested +# before they reach a file whose failure mode is "no project starts". +# +# Behavior is deliberately identical to the inline block it replaces, including +# its rough edges. Anything that looks like a defect here is characterized by a +# test rather than fixed in passing — a change of behavior belongs in its own +# commit, not smuggled into an extraction. +# +# Usage: sync-templates [project-root] (default: $PWD) +# Output: one line naming the outcome, matching the previous inline wording +# Exit: 0 always, as the inline block did — the outcome is on stdout +# +# Two guards, and they work differently. One withholds files; the other skips +# the whole run: +# +# Rulesets dirty under the synced paths → withhold exactly those files. +# rsync -a --delete copies the working tree by disk presence, so an in-flight +# edit in rulesets would otherwise land downstream as drift the project never +# authored. Each dirty path becomes an --exclude, which rsync honors on both +# sides: the file is neither overwritten nor deleted downstream, and every +# clean file still propagates. This was a global skip until 2026-07-31, which +# meant one uncommitted file in rulesets froze every template for every +# project until it was committed. +# +# Project branch behind its upstream → skip the whole sync. Syncing onto a +# stale committed .ai/ baseline measures the diff against old content, so it +# comes out huge and conflicts once the branch reconciles to an upstream that +# already carries the newer templates. This one stays all-or-nothing because +# the staleness is in the destination, not in any particular source file. +# +# The rulesets location is injectable (SYNC_RULESETS_DIR) so the guards can be +# exercised against a fixture instead of the real checkout. + +rs="${SYNC_RULESETS_DIR:-$HOME/code/rulesets}" +proj="${1:-$PWD}" + +cd "$proj" || { + echo "sync-templates: cannot enter '$proj'" >&2 + exit 0 +} + +# The dirty set under the synced paths, one repo-relative path per line. +# core.quotePath=false keeps a non-ASCII filename literal instead of \xNN-escaped, +# so the path we build an --exclude from is the path on disk. +synced_dirty=$(cd "$rs" && git -c core.quotePath=false status --porcelain -- \ + claude-templates/.ai/protocols.org \ + claude-templates/.ai/workflows/ \ + claude-templates/.ai/scripts/ 2>/dev/null) + +# Turn that set into per-rsync --exclude flags rather than a global skip. An +# excluded path is neither overwritten nor deleted on the receiving side, so an +# in-flight edit stays in-flight while every file it doesn't touch propagates +# normally. The all-or-nothing skip this replaces is what caused the 2026-07-30 +# outage: one uncommitted workflow file withheld every template from every +# project for a full day. +protocols_dirty=0 +wf_excludes=() +sc_excludes=() +withheld=() + +while IFS= read -r line; do + [ -z "$line" ] && continue + path="${line:3}" + # A rename reports "old -> new". Withhold both sides: the new name is + # half-landed, and sweeping the old copy downstream would delete a file the + # project still runs while the rename sits uncommitted. + if [[ "$path" == *" -> "* ]]; then + paths=("${path%% -> *}" "${path##* -> }") + else + paths=("$path") + fi + for p in "${paths[@]}"; do + p="${p%\"}"; p="${p#\"}" + case "$p" in + claude-templates/.ai/protocols.org) + # A single-file rsync has nothing to exclude within, so this one + # transfer is skipped outright while the other two still run. + protocols_dirty=1 + withheld+=("$p") + ;; + claude-templates/.ai/workflows/*) + # Leading / anchors the pattern to the transfer root, so a dirty + # workflows/foo.org can't also suppress scripts/tests/foo.org. + wf_excludes+=("--exclude=/${p#claude-templates/.ai/workflows/}") + withheld+=("$p") + ;; + claude-templates/.ai/scripts/*) + sc_excludes+=("--exclude=/${p#claude-templates/.ai/scripts/}") + withheld+=("$p") + ;; + esac + done +done <<< "$synced_dirty" + +# behind==0 (up-to-date or ahead-only) means HEAD contains all of upstream, so +# the baseline is current. No upstream (new/unpushed branch) → rev-list fails → +# proj_behind stays 0 → the sync runs. +proj_behind=0 +if [ -d .git ]; then + counts=$(git rev-list --left-right --count '@{u}...HEAD' 2>/dev/null) \ + && [ "$(printf '%s' "$counts" | cut -f1)" -gt 0 ] 2>/dev/null \ + && proj_behind=1 +fi + +if [ "$proj_behind" -eq 1 ]; then + echo "project branch is behind upstream — skipping .ai/ sync this session (templates never land on a stale baseline; the sync runs once the branch is current)" +else + [ "$protocols_dirty" -eq 0 ] && rsync -a "$rs/claude-templates/.ai/protocols.org" .ai/protocols.org + rsync -a --delete "${wf_excludes[@]}" "$rs/claude-templates/.ai/workflows/" .ai/workflows/ + # Running rulesets' own pytest leaves these in the canonical scripts/tests/, + # and rsync -a copies by disk presence regardless of .gitignore, so without + # the excludes every project's tree collects machine-specific cache files. + rsync -a --delete --exclude='__pycache__' --exclude='.pytest_cache' --exclude='*.pyc' \ + "${sc_excludes[@]}" "$rs/claude-templates/.ai/scripts/" .ai/scripts/ + # Known false-success path, inherited and characterized rather than fixed + # here: this line prints unconditionally, so a run where all three rsyncs + # failed (an absent canonical source, say) still reports a successful sync. + # A last-synced manifest must not be written from this branch as it stands — + # it would stamp success onto a sync that did nothing. + echo ".ai/ synced from templates" + if [ ${#withheld[@]} -gt 0 ]; then + echo " withheld — uncommitted in rulesets, lands once committed:" + printf ' %s\n' "${withheld[@]}" + fi +fi diff --git a/.ai/scripts/tests/sync-templates.bats b/.ai/scripts/tests/sync-templates.bats new file mode 100644 index 0000000..6651c99 --- /dev/null +++ b/.ai/scripts/tests/sync-templates.bats @@ -0,0 +1,319 @@ +#!/usr/bin/env bats +# Characterization tests for sync-templates — the mechanism that distributes +# every template change to every project. +# +# These pin CURRENT behavior (record-not-spec) ahead of the guard changes the +# 2026-07-30 propagation incident calls for. That incident is what these exist +# for: an uncommitted edit in rulesets silently blocked all three rsyncs for a +# whole day, and five workflow files went stale in one downstream project alone +# with nothing anywhere reporting it. Any change to this script's guards has to +# come with a red test here first. +# +# Everything runs against fixture directories via SYNC_RULESETS_DIR, so no test +# touches the real rulesets checkout or any real project. + +setup() { + # This suite lives beside the script it tests and travels with it, so it + # resolves the script relative to itself rather than to a repo root. + SYNC="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/sync-templates" + WORK="$(mktemp -d)" + RS="$WORK/rulesets" + PROJ="$WORK/proj" + export SYNC_RULESETS_DIR="$RS" + + # A minimal rulesets fixture: a git repo with the three synced source paths. + mkdir -p "$RS/claude-templates/.ai/workflows" "$RS/claude-templates/.ai/scripts" + printf 'canonical protocols\n' > "$RS/claude-templates/.ai/protocols.org" + printf 'canonical startup\n' > "$RS/claude-templates/.ai/workflows/startup.org" + printf 'canonical helper\n' > "$RS/claude-templates/.ai/scripts/helper" + # Real rulesets gitignores the python cache paths, so they never make the + # tree dirty. Without this the fixture diverges from production in a way + # that silently disarms the exclusion test: the cache files read as + # untracked, guard one fires, the sync never runs, and assertions that the + # cache did NOT arrive pass because nothing arrived at all. + printf '__pycache__/\n.pytest_cache/\n*.pyc\n' > "$RS/.gitignore" + _mk_repo "$RS" + + # A consuming project with the destination dirs. + mkdir -p "$PROJ/.ai/workflows" "$PROJ/.ai/scripts" +} + +teardown() { rm -rf "$WORK"; } + +_mk_repo() { + local d="$1" + git init -q "$d" + git -C "$d" config user.email t@example.com + git -C "$d" config user.name tester + git -C "$d" config commit.gpgsign false + git -C "$d" config gc.auto 0 + git -C "$d" config maintenance.auto false + git -C "$d" add -A + # --allow-empty: the project fixture holds only empty directories, which git + # has nothing to commit, and these tests need it to be a repo with a HEAD. + git -C "$d" commit -q --allow-empty -m init +} + +# --- the happy path ------------------------------------------------------------ + +@test "clean rulesets and a non-git project: syncs all three paths" { + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] + [ "$(cat "$PROJ/.ai/protocols.org")" = "canonical protocols" ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "canonical startup" ] + [ "$(cat "$PROJ/.ai/scripts/helper")" = "canonical helper" ] +} + +@test "--delete removes a retired template file from the project" { + printf 'retired\n' > "$PROJ/.ai/workflows/gone.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] + [ ! -e "$PROJ/.ai/workflows/gone.org" ] +} + +@test "the scripts sync excludes python cache artifacts" { + mkdir -p "$RS/claude-templates/.ai/scripts/__pycache__" \ + "$RS/claude-templates/.ai/scripts/.pytest_cache" + printf 'junk\n' > "$RS/claude-templates/.ai/scripts/__pycache__/x.pyc" + printf 'junk\n' > "$RS/claude-templates/.ai/scripts/.pytest_cache/y" + printf 'junk\n' > "$RS/claude-templates/.ai/scripts/stray.pyc" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + # Assert the sync RAN before asserting what it didn't copy. Without this the + # absences below are satisfied by a skipped sync, and the whole test passes + # with every --exclude flag deleted from the script. + [[ "$output" == *"synced from templates"* ]] + [ -e "$PROJ/.ai/scripts/helper" ] + [ ! -e "$PROJ/.ai/scripts/__pycache__" ] + [ ! -e "$PROJ/.ai/scripts/.pytest_cache" ] + [ ! -e "$PROJ/.ai/scripts/stray.pyc" ] +} + +@test "project-owned directories are never touched by the sync" { + mkdir -p "$PROJ/.ai/project-workflows" "$PROJ/.ai/project-scripts" + printf 'mine\n' > "$PROJ/.ai/project-workflows/local.org" + printf 'mine\n' > "$PROJ/.ai/project-scripts/local.py" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] + [ "$(cat "$PROJ/.ai/project-workflows/local.org")" = "mine" ] + [ "$(cat "$PROJ/.ai/project-scripts/local.py")" = "mine" ] +} + +# --- guard one: rulesets dirty under the synced paths -------------------------- + +@test "a dirty file is withheld from the sync and named in the output" { + printf 'in-flight edit\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + printf 'stale\n' > "$PROJ/.ai/workflows/startup.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"withheld"* ]] + [[ "$output" == *"startup.org"* ]] + # The in-flight edit still must not land downstream. + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "stale" ] +} + +@test "ONE dirty file no longer blocks the other two rsyncs" { + # The 2026-07-30 incident, inverted. An edit to a workflow file used to + # withhold protocols.org and every script for every project; now it withholds + # only itself. + printf 'in-flight edit\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + printf 'stale protocols\n' > "$PROJ/.ai/protocols.org" + printf 'stale helper\n' > "$PROJ/.ai/scripts/helper" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ "$(cat "$PROJ/.ai/protocols.org")" = "canonical protocols" ] + [ "$(cat "$PROJ/.ai/scripts/helper")" = "canonical helper" ] +} + +@test "a dirty file's clean siblings under the SAME path still sync" { + printf 'canonical wrap\n' > "$RS/claude-templates/.ai/workflows/wrap.org" + git -C "$RS" add -A && git -C "$RS" commit -q -m 'add wrap' + printf 'in-flight edit\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + printf 'stale wrap\n' > "$PROJ/.ai/workflows/wrap.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + # The narrowing is per-file, not per-directory: only startup.org is held back. + [ "$(cat "$PROJ/.ai/workflows/wrap.org")" = "canonical wrap" ] +} + +@test "an excluded file is not deleted by --delete either" { + # rsync honors --exclude on both sides, so a withheld file that exists + # downstream must survive the run rather than being swept as a stray. + printf 'in-flight edit\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + printf 'project copy\n' > "$PROJ/.ai/workflows/startup.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ -e "$PROJ/.ai/workflows/startup.org" ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "project copy" ] +} + +@test "a dirty protocols.org withholds only itself; workflows and scripts sync" { + printf 'in-flight edit\n' >> "$RS/claude-templates/.ai/protocols.org" + printf 'stale protocols\n' > "$PROJ/.ai/protocols.org" + printf 'stale startup\n' > "$PROJ/.ai/workflows/startup.org" + printf 'stale helper\n' > "$PROJ/.ai/scripts/helper" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ "$(cat "$PROJ/.ai/protocols.org")" = "stale protocols" ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "canonical startup" ] + [ "$(cat "$PROJ/.ai/scripts/helper")" = "canonical helper" ] +} + +@test "dirty files across two synced paths withhold both, sync the third" { + printf 'in-flight\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + printf 'in-flight\n' >> "$RS/claude-templates/.ai/scripts/helper" + printf 'stale startup\n' > "$PROJ/.ai/workflows/startup.org" + printf 'stale helper\n' > "$PROJ/.ai/scripts/helper" + printf 'stale protocols\n' > "$PROJ/.ai/protocols.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "stale startup" ] + [ "$(cat "$PROJ/.ai/scripts/helper")" = "stale helper" ] + [ "$(cat "$PROJ/.ai/protocols.org")" = "canonical protocols" ] +} + +@test "an untracked file under a synced path is withheld, not blocking" { + printf 'new template\n' > "$RS/claude-templates/.ai/workflows/brand-new.org" + printf 'stale protocols\n' > "$PROJ/.ai/protocols.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"withheld"* ]] + # An unfinished new template must not ship half-written... + [ ! -e "$PROJ/.ai/workflows/brand-new.org" ] + # ...and must not hold back everything else. + [ "$(cat "$PROJ/.ai/protocols.org")" = "canonical protocols" ] +} + +@test "an untracked DIRECTORY under a synced path is withheld whole" { + # git collapses an untracked dir to one porcelain line with a trailing slash + # ("?? .../plugins/"), so the exclude has to match the directory rather than + # the files inside it. A half-written plugin dir must not ship. + mkdir -p "$RS/claude-templates/.ai/workflows/plugins" + printf 'half written\n' > "$RS/claude-templates/.ai/workflows/plugins/new.org" + printf 'stale protocols\n' > "$PROJ/.ai/protocols.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ ! -e "$PROJ/.ai/workflows/plugins" ] + [ "$(cat "$PROJ/.ai/protocols.org")" = "canonical protocols" ] +} + +@test "a file dirty in the index (staged, uncommitted) is withheld too" { + printf 'staged edit\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + git -C "$RS" add claude-templates/.ai/workflows/startup.org + printf 'stale\n' > "$PROJ/.ai/workflows/startup.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "stale" ] +} + +@test "a renamed template withholds both the old and the new path" { + git -C "$RS" mv claude-templates/.ai/workflows/startup.org \ + claude-templates/.ai/workflows/renamed.org + printf 'stale startup\n' > "$PROJ/.ai/workflows/startup.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + # The new name must not ship mid-rename, and the old copy must not be swept + # while the rename is still uncommitted. + [ ! -e "$PROJ/.ai/workflows/renamed.org" ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "stale startup" ] +} + +@test "rulesets dirt OUTSIDE the synced paths does not block the sync" { + printf 'scratch\n' > "$RS/scratch.txt" + printf 'edit\n' >> "$RS/claude-templates/bin-ish.txt" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] +} + +# --- guard two: the project branch is behind its upstream ---------------------- + +@test "a project behind its upstream skips the sync" { + _mk_repo "$PROJ" + git init -q --bare "$WORK/remote" + git -C "$PROJ" remote add origin "$WORK/remote" + git -C "$PROJ" push -q -u origin HEAD + git -C "$PROJ" commit -q --allow-empty -m ahead + git -C "$PROJ" push -q origin HEAD + git -C "$PROJ" reset -q --hard HEAD~1 + printf 'stale\n' > "$PROJ/.ai/workflows/startup.org" + + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"behind upstream"* ]] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "stale" ] +} + +@test "a project AHEAD of its upstream still syncs" { + _mk_repo "$PROJ" + git init -q --bare "$WORK/remote" + git -C "$PROJ" remote add origin "$WORK/remote" + git -C "$PROJ" push -q -u origin HEAD + git -C "$PROJ" commit -q --allow-empty -m ahead + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] +} + +@test "a git project with no upstream syncs (rev-list fails, guard stays off)" { + _mk_repo "$PROJ" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] +} + +# --- edges --------------------------------------------------------------------- + +@test "a nonexistent project directory reports and exits 0 without syncing" { + run bash "$SYNC" "$WORK/does-not-exist" + [ "$status" -eq 0 ] + [[ "$output" == *"cannot enter"* ]] + [[ "$output" != *"synced from templates"* ]] + [ ! -e "$WORK/does-not-exist" ] +} + +@test "the sync is idempotent — a second run changes nothing" { + bash "$SYNC" "$PROJ" + first="$(find "$PROJ/.ai" -type f -exec sha256sum {} + | sort)" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] + second="$(find "$PROJ/.ai" -type f -exec sha256sum {} + | sort)" + [ "$first" = "$second" ] +} + +@test "a missing canonical source still reports success — the false-success path" { + # Faithfully inherited from the inline block, and pinned here because the + # manifest step depends on it: a last-synced record written after this + # branch would stamp a successful sync onto one where all three rsyncs + # failed. The guard work has to fix this before it can trust the record. + # Point at a rulesets that isn't there at all, rather than deleting the + # canonical subtree inside a live repo — that would show up as staged + # deletions and trip guard one, which is a different path entirely. + SYNC_RULESETS_DIR="$WORK/no-such-rulesets" run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] + # Nothing arrived, and the success line says otherwise. Asserted against a + # file that DOES arrive on a real sync — protocols.org is absent before any + # sync too, so its absence alone would prove nothing. + [ ! -e "$PROJ/.ai/scripts/helper" ] +} + +@test "a locally-edited template is silently overwritten, with no record kept" { + # Work's 2026-07-30 regression, pinned: a project patches a rulesets-owned + # file, the next sync reverts it to canonical, and nothing anywhere says so. + # The output is indistinguishable from an ordinary successful sync. + bash "$SYNC" "$PROJ" + printf 'local fix for a real bug\n' > "$PROJ/.ai/workflows/startup.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "canonical startup" ] + [[ "$output" == *"synced from templates"* ]] + # No warning, no backup, no manifest — the loss leaves no trace at all. + [[ "$output" != *"overwrote"* ]] + [[ "$output" != *"local edit"* ]] + [ ! -d "$PROJ/.ai/.sync-backups" ] +} diff --git a/.ai/scripts/tests/test-todo-cleanup.el b/.ai/scripts/tests/test-todo-cleanup.el index a92d238..1e964b3 100644 --- a/.ai/scripts/tests/test-todo-cleanup.el +++ b/.ai/scripts/tests/test-todo-cleanup.el @@ -1086,7 +1086,7 @@ line) is left untouched — the strip stops at the first non-planning line." ;; ;; todo-cleanup rewrites todo.org in place and left no copy behind, while both ;; sibling org-mutators back up to /tmp first. It is also the one that runs most -;; often (every wrap, every sentry fire). Emacs's own backup does not fire under +;; often (every wrap, every sentry cycle). Emacs's own backup does not fire under ;; --batch -q, so there was genuinely no undo short of git. (ert-deftest tc-backup-written-before-a-real-mutation () diff --git a/.ai/scripts/todo-cleanup.el b/.ai/scripts/todo-cleanup.el index cb333e2..516e9b1 100644 --- a/.ai/scripts/todo-cleanup.el +++ b/.ai/scripts/todo-cleanup.el @@ -843,7 +843,7 @@ event-log entry, pulling the timestamp from its CLOSED cookie. Honors Matches `lint-org.el' and `wrap-org-table.el', the other tools that rewrite these org files. todo-cleanup runs the most often of the three (every wrap, -every sentry fire), and Emacs's own backup does not fire under --batch -q, so +every sentry cycle), and Emacs's own backup does not fire under --batch -q, so without this a mechanical rewrite has no undo short of git — which recovers only to the last commit and loses intra-session work." (let* ((base (format "%s%s.before-todo-cleanup.%s" diff --git a/.ai/sessions/2026-07-27-17-02-context-engineering-rightsizing.org b/.ai/sessions/2026-07-27-17-02-context-engineering-rightsizing.org new file mode 100644 index 0000000..54020e4 --- /dev/null +++ b/.ai/sessions/2026-07-27-17-02-context-engineering-rightsizing.org @@ -0,0 +1,176 @@ +* Summary + +** Active Goal + +Review three Anthropic posts on context engineering against what this repo ships downstream, then act on the findings. Ended with the always-loaded rules surface cut from ~57,800 tokens to ~28,949 (plus 13,461 path-scoped), two mechanisms proven in a live session, and two of my own bugs found and fixed — one of which had killed Craig's work session. + +** Decisions + +- *Split rules by blast radius, not by size.* What must hold whether or not you're publishing, and where a violation is permanent and reaches other people, stays always-loaded. Everything recoverable can ride a trigger. That's what let =commits.md= and =testing.md= ship without waiting on any pilot. +- *Goal is output quality first, tokens second* (Craig's correction). Anthropic's 80% was a finding, not a target. P4/Phase 8 (effort reduction) dropped outright for trading quality for cost; P5 (positive framing over prohibition) promoted as the lever that actually targets guardrails working against output. +- *Don't apply the posts additively.* The harness system prompt already carries most of what the Opus 5 guide recommends adding, near-verbatim. Adding it to =claude-rules/= would worsen the duplicate-and-conflict problem the first post opens with. The posts' value here is subtractive. +- *Everything authored in or about the repo is first person* (Craig's instruction), with one carve-out: a comment describing what the code does stays third person, since there the code is the actor. +- *No unmerging home.* Its domains are already separated by tag (24 finances, 18 kit, 17 jrestate). The real problem is a tag namespace flattening four orthogonal axes, and cross-domain priority is a judgment no scheme can make — splitting projects hides the question rather than answering it. + +** Data Collected / Findings + +- *Path-scoping works at user level*, confirmed by =/context= in a live work session: 17 generic rules listed, the three path-scoped ones absent. Deterministic glob match, so no trial needed for that tier. +- *User-level and project-level rules both load, project wins.* work and =.emacs.d= carried 19 byte-identical duplicates, and a stale project copy silently overrode the fresh global rule. +- *My token estimates were 45% low.* Real ratio 2.28 tok/word. =commits.md= was 12,800 tokens, not the ~7,000 I claimed. =/context= reported the true per-file numbers the whole time and I used a word-count estimate because it was easier to compute from inside the repo. +- *Two loading paths, not one.* Memory files arrive via the harness; =protocols.org= and the workflows are read by startup and land in Messages. They shrink by editing the workflow, not by scoping a rule. +- *41 execution/hygiene workflows against 6 discovery/design.* The system is heavily built on the half of the problem that got easier. +- *The instructions don't practice what they demand:* =commits.md= argued terseness at 5,561 words, =interaction.md= bans bold while the rules carry 591 bold markers, =testing.md= argues TDD across eight more rows of rationalizations. +- *Two of my own mechanical guards failed the same day, both certifying success while doing damage.* =wrap-org-table.el= reflowed a table into a worse shape and =lint-org= then passed it; the wrap-teardown hook consumed a two-hour-old sentinel and killed Craig's live work session. + +** Files Modified + +Seven commits, all pushed, velox synced throughout. =6c1ea8b= peer-reasoning rule + Chrome convention + KB probe fix. =0adcb1a= =paths:= frontmatter on the three file-type rules + the lint checker that catches prose/frontmatter mismatch. =7ea1d7b= generic rules no longer ship per project, sweep + gitignored session anchor. =79ed3b0= the three rightsizing docs. =2c664cb= =hooks/session-start-disarm.sh= for the sentinel bug. =d74d98d= docs corrected against live measurements. =931f364= =commits.md= → invariant core + =publish= skill. =2f45b6e= =testing.md= → directive core + =testing-standards= skill, approval-gate signal fixed, first-person directive. + +** Next Steps + +Everything remaining needs Craig's decisions rather than execution — see the =[#B] Finish context-engineering rightsizing= task and the =[2026-07-27]= reminder. In order: reconcile the three working docs (one commit behind), then C1 (=verification.md='s honesty core vs the over-verification warning), =interaction.md=, the TDD rationalization table, and D3 (which approval gates are preference vs guardrail). + +Also open: the work sentry triage split and the recurring-loop proposal, both filed =[#B]= with their reviews. The sentry spec review is still waiting, now two weeks old. + +KB: promoted 2 / consulted no + +* Session Log + +** Startup — 2026-07-27 10:25 CDT + +Ran startup. Rulesets already current; =make install= had nothing new to link; project repo clean at f2609d9 with no upstream drift. =.ai/= synced from templates (no churn — the sync is a no-op mirror refresh in this repo). Previous session wrapped cleanly (no session-context anchor present). + +Startup signals: 6 top-level tasks unreviewed for >7 days; roam inbox empty; KB at 106 =:agent:= nodes but the best-practices node path resolved empty (=rg -l 'agent-kb-best-practices'= found nothing — worth checking whether that node exists); no spec-sort or host-identity flags; language-bundle sync silent. + +Five new inbox handoffs arrived since the last wrap. Read all five and ran the skeptical review on each before surfacing dispositions. + +Disposed of one without asking: home's 07-26 10:21 file was a pure FYI acknowledging that the parked MCP-registry spec decision and the separate memory-auditor track matched its handoff. It asked for nothing, so it needed no reply and no approval — deleted it. Four remain, all shared-asset or convention changes, all waiting on Craig's approval per the inbox engine's core §2. + +Skeptical-review conclusions on the four pending: + +- *archsetup publish-lock* — design sound, acceptance checks testable. Three gaps: TTL sizing has to survive an indefinite human approval wait (refresh-on-re-entry covers the agent, not a Craig who steps away); the blocked second session's behavior (wait / defer / stop) is unspecified; and it's a real build, not a quick edit. Recommend filing =[#B] :feature:=. +- *home Chrome convention* — protocols.org already prefers google-chrome-stable over xdg-open, so the new parts are =--new-tab=, multi-URL, and the confirmation line. The confirmation half contradicts the existing =&>/dev/null &= form, which discards exactly the message to be verified. Recommend applying with a foreground-when-running / background-on-cold-start reconciliation. +- *work sentry triage correction* — Craig's 07-27 correction supersedes his 07-21 ruling; today's work fire missed a Hayk DM and a Kostya PR-review request. The gap is that the current rule excludes by category (mail / messenger) and the new split is work-vs-personal, which category can't express. Shipping plugins: cmail, personal-gmail, personal-calendar, telegram, github-prs — no general work-mail plugin, so work's source is project-specific. A denylist of personal plugin names fails open on the next personal source added; a per-plugin eligibility declaration is the durable shape, and that's a design call. Recommend filing =[#B] :bug:= (Major × most-users-frequently = P2). +- *work peer-reasoning rule* — approved exact text, well-formed. Two notes: it's a reasoning contract in a file scoped to communication style (the framing line should widen), and "process serves the outcome" sits one reading away from licensing deviation from the mandatory gates. Its own wording says surface-before-proceeding, so no edit needed, but that's the line to watch. Recommend installing as written. + +** Inbox pass applied — commit 6c1ea8b + +Craig approved all four dispositions plus the probe fix. Two corrections from him along the way: I had inverted the render-merge guard (numerals belong to the options list, dashes to every other enumeration in the same message — I did the reverse), and processed items shouldn't be left sitting in =inbox/=. + +Shipped: the peer-reasoning section at the top of =claude-rules/interaction.md= with the file's framing line widened; the Chrome convention rewritten in canonical =protocols.org=; the KB best-practices probe switched from a content grep to a filename =find=. Filed two =[#B]= tasks (sentry triage split, repository publish-lock), both stamped =:LAST_REVIEWED: 2026-07-27=. Swept the 40-file =PROCESSED-*= backlog out of =inbox/= along with the four handoffs; =inbox-status= now reports 0. Replies sent to archsetup, home, and work. + +*The review caught my own error.* I had written that Chrome's confirmation line prints to stderr and told every project to capture it with =2>&1=. It prints to *stdout*; stderr is empty. Verified both directions on ratio before correcting. An agent following the original text would have captured stderr, seen nothing, and concluded the tab failed to open — the exact silent-failure shape as the KB probe it shipped alongside. I asserted a stream rather than checking it, inside the same change that told others to verify. Side effect: four =about:blank= tabs opened in Craig's live browser during the check. + +Deliberate departure recorded: =route_recommend= returned =work strong= for the sentry task, but the work happens in rulesets' canonical =sentry.org=, so it's a local keeper and I left it unstamped rather than letting the wrap router offer to ship it away. + +Possible KB promotion at wrap: an identifier that lives only in a filename is invisible to a content search, and the lookup fails *silently* rather than erroring. Adjacent to the existing enumerate-vs-discover node but a distinct failure surface. Two instances in one commit (the KB probe, the Chrome stream) argue it generalizes. + +Startup-workflow bug found while checking the KB nudge: Phase A resolves the best-practices node with =rg -l 'agent-kb-best-practices' "$ra"=, which greps file *content*. The node's slug lives in its filename, so the probe returns empty and the contribute nudge points at nothing — in every project, every session. The node exists at =~/org/roam/agents/20260620232112-agent-kb-best-practices.org=. Synced-workflow change, so it waits on approval too. + +** Pushed and synced velox + +Pushed 6c1ea8b to origin/main (ahead-only, reconciled immediately before). On ratio, so velox needed the pull: it fast-forwarded and =make install= linked three things it had been missing since 2026-07-25 — the Codex =hooks.json=, =rulesets-write-boundary.py=, and =git-worktree-gate=. That drift is exactly the one-time-setup case =daily-drivers.md= names: the files traveled with the pull, but nothing re-runs the installer, so the symlinks only land where someone runs it. A new Codex session on velox will now hit the hook review/trust prompt, which was already on the 2026-07-25 next-steps list. + +** Context-engineering rightsizing — analysis and rollout plan + +Craig supplied three Anthropic posts (the 2026-07-24 Claude 5 context-engineering post, the Opus 5 prompting guide, the 2026-07-06 Fable field guide) and asked for a review, proposals, and a consistency audit of what this repo ships downstream. Then he reframed twice, and both reframes were better than the question I'd been answering. + +*First reframe:* consider the files as *his prompts*, not my context. That changed the finding. My first pass measured the always-loaded surface (32,123 words — =claude-rules/= 25,386 + =protocols.org= 6,620 + CLAUDE.md 117, roughly 40k tokens before the user's first word) and proposed shrinking it. Read as a map he hands every project, the finding is different: 41 execution/hygiene workflows against 6 discovery/design, seven to one. That ratio was right when the risk was the model doing things wrong. The field guide's claim is the bottleneck moved to the human's ability to clarify unknowns, so the system is heavily built on the half that got easier. + +*Second reframe:* metrics per claim, not one go/no-go. Turns the rollout into a set of separable testable claims rather than one bet. + +Three checkable "doesn't practice what it demands" findings: =commits.md= argues terseness at 5,561 words (longest file in the set); =interaction.md= bans bold in chat while the rules carry 591 bold markers; =testing.md= mandates TDD then argues eight more rows against rationalizations. + +*The finding that changed the plan:* the harness system prompt already carries most of what the Opus 5 guide recommends adding — its task-scope block, correction-narration block, and subagent cap are present nearly verbatim, and post 1's replacement comment guidance is present as the post's own new wording. So applying the posts additively would make the duplicate-and-conflict problem worse. The posts' value here is subtractive. It also exposes a third dedup axis nobody has audited: =claude-rules/= against the harness prompt, invisible from inside the repo. + +*Pilot selection rule* (the part that matters more than the list): the six pilot files were chosen because a silent miss is *detectable*, not because they're small. Four have a mechanical checker (=lint-org= =org-table-standard=, spec-board grep, =spec-review=), two produce an error Craig sees in seconds. =daily-drivers.md= and =emacs.md= were considered and held back — low risk, but a miss surfaces too slowly to learn from inside the trial window. + +Artifacts in =working/context-engineering-rightsizing/=: =proposals.org= (P1-P6, conflicts C1-C2, the from-your-side-of-the-desk section), =rollout.org= (Phases 0-8, decisions D1-D7, target trajectory), =metrics.org= (claim-by-claim testability, pilot go/no-go with the denominator rule, turn-back vs abandon triggers). + +Two honesty notes carried into the docs: I have a stake in arguing my own instructions should be shorter, so the plan weights mechanical detectors over my self-report; and about half the posts' claims aren't testable here without an eval harness, so those are labelled judgment rather than measurement so a future session doesn't mistake an adopted opinion for a tested result. + +Not started. Awaiting D1 (confirm pilot set) and D2 (skill index in the core). + +** Path-scoping shipped (0adcb1a) and work pre-synced + +The session's biggest finding: Claude Code scopes a rule by a =paths:= field in YAML frontmatter, and none of the 20 rules had one — even though three already declared a file-type scope in their =Applies to:= prose line. So =todo-format.md= (4,494), =org-tables.md= (464), and =emacs.md= (923) loaded into every session in every project, contradicting their own first line. 5,896 words. Fixed by adding the frontmatter, plus a =lint.sh= checker that warns when prose names a concrete extension without matching frontmatter (flags exactly those three, nothing else), plus teaching the heading check to skip a frontmatter block. Always-loaded rules surface: 25,386 → 19,505. + +Also confirmed from the docs: user-level and project-level rules *both* load, and project rules take priority. So work and =.emacs.d= carry 19 byte-identical duplicate copies, and a stale project copy overrides a fresh global one — which is exactly what was happening to work's =interaction.md= between this morning's commit and its next startup. + +Pre-synced work via =scripts/sync-language-bundle.sh ~/projects/work= (rulesets' own installer, run early rather than waiting for work's startup) so Craig's next work session is a valid test rather than one running the set it loaded before the sync. Verified: all four files now match canonical, frontmatter present, and work's =.claude/= is gitignored there so nothing was dirtied. + +Open question the next session answers: does =paths:= frontmatter apply to *user-level* rules or project-level only? The docs don't draw the distinction. =/context= in a fresh session settles it — if =todo-format.md= is absent from Memory files until an org file is opened, it works. If it's listed, the frontmatter is inert (no harm) and semantic skills are the only route. + +Not done: the double-load fix. Removing the 19 duplicates means changing what =install-lang= pushes into projects, and there may be a teammate-facing reason for them. Surfaced as Craig's call, not urgent — wasteful, not harmful. + +** De-duplicated the rules layer, unblocked sync (7ea1d7b, 79ed3b0) + +Craig confirmed no teammates depend on the per-project rule copies, so I removed them. =install-lang.sh= no longer copies the generic rules; =sync-language-bundle.sh= sweeps the ones earlier installs left, guarded on the global rule existing so a machine mid-bootstrap isn't stranded with none. Swept 20 files each from work and =.emacs.d=, leaving only their language rules plus work's =publishing.md= overlay. Three existing tests encoded the old contract and were rewritten; the generic-drift test now asserts sweep-not-repair, which is the stronger fix since the drifted copy outranked the global rule while it existed. Four new tests cover the sweep, the two keep-cases, and the no-global-rule guard. + +Also gitignored =.ai/session-context.org= and =.ai/session-context.d/=. This repo tracks =.ai/=, so the live anchor read as untracked all session and =git-worktree-gate= reported rulesets sync-blocked — meaning every other project skipped its rulesets pull until wrap, every session. Craig spotted the blocked state and inferred it was why I pre-synced work; it wasn't (rules load at launch, before the startup sync runs, which was the real reason), but chasing his inference found the anchor problem, which was the better bug. + +Corrections from Craig this stretch: the goal is output quality first, token reduction second — my docs led with the wrong number and P4 (effort reduction) should be demoted or dropped since it trades quality for cost. And all authored prose goes first person; I amended the first commit rather than leaving it. Code comments stay third-person by agreement, since they describe what the code does for the next reader. + +Docs not yet updated for either the goal reordering or the last two hours of findings (path-scoping, the double-load, the harness overlap). That's the next task. + +** Inbox: archsetup ack + +archsetup acknowledged the publish-lock acceptance and the three implementation gaps, confirming the decision stays closed on its side. Pure FYI, nothing asked, no reply owed. Deleted it. Inbox back to zero. + +** Killed Craig's work session with my own hook, then fixed it (2c664cb) + +Craig's 13:20 work session was blocked repeatedly and then had its terminal closed under it. The cause was mine, from Saturday's clean-wrap work. + +=wrap-it-up= drops =/tmp/ai-wrap-teardown-<project>= so the =Stop= hook tears down once the wrap certifies clean. I deliberately made a failed certification *preserve* the sentinel, so a wrap blocked by a dirty tree could retry on a later stop. I never bounded that retry to the session. work's 11:37 wrap left an uncertified sentinel armed; the 13:20 session's stops were all blocked by it failing certification; then startup's two commits (task filing, template sync) made the tree clean, the next stop certified, and =cj/ai-term-quit= killed the tmux session mid-work. + +Two others were armed and dangerous at the same moment: archsetup's since Saturday 15:02 on a live attached terminal, and home's from 13:21 on a live session. Disarmed all three by hand (backed up to =/tmp/disarmed-sentinels=) before writing any fix, since both were minutes from the same fate. + +Fix: =hooks/session-start-disarm.sh= clears the project's sentinels at =SessionStart= — a new session means the wrap that armed one is gone. Within-session retry is untouched (the hook only runs at session start) and a test pins that so the deliberate behavior isn't lost to the fix. Four tests on the disarm including project-scoping, one on the retry. Wired into =.claude/settings.json=, installed on both machines, =wrap-it-up.org= documents the session-scoping with the worked failure. + +Diagnostic note worth keeping: I found it by reading work's own crashed session anchor, which showed startup completing normally and then stopping dead, plus its git log showing two commits at 13:21 — the exact moment the tree went clean. The anchor being left behind by the interrupted session is what made the timeline reconstructable. That's the crash-recovery purpose earning itself. + +** /context settled both open questions; docs corrected (d74d98d) + +Craig ran =/context= in work. Memory files lists 17 generic rules; =todo-format.md=, =org-tables.md=, and =emacs.md= are absent, and only =python-testing.md= and =publishing.md= come from the project's own rules dir. So *path-scoping works at user level* and *the de-duplication holds*. Both were open. + +Three corrections the live numbers forced: + +1. *My token figures were low by ~45%.* Real ratio is 2.28 tok/word, not the ~1.3 I assumed. =commits.md= is 12,800 tokens (I said ~7,000); =claude-rules/= was ~57,800/session before today, now 44,410, with 13,390 path-scoped out. Worth naming the actual error: =/context= reports per-file token counts and I used a word-count estimate instead because it was easier to compute from inside the repo. The instrument existed the whole time. +2. *Two loading paths, not one.* Memory files arrive via the harness at session start. =protocols.org= and the workflows are *read by startup*, so they land in Messages and never appear under Memory files. They shrink by editing the workflow, not by scoping a rule. My "always-loaded surface" number conflated them. +3. *The harness's own suggestion* names =commits.md=, =testing.md=, =MEMORY.md= as the top three to prune — independently the same Phase 4 list I'd proposed. + +Because a glob match is deterministic, the remaining work splits: path-scopable rules ship with no trial (=docs-lifecycle.md= on =docs/**= is next), and only semantic-condition rules need the skills route and the stop conditions. =commits.md= is the real test there — largest single item, and almost all publish machinery that only applies when a commit is in play. + +Recorded a caution the confirmation doesn't cover: path-scoping fires on a *read* of a matching file, so creating a new org file from scratch never triggers =todo-format.md=. Edits are safe (Edit requires a prior read). + +Also folded in Craig's goal correction (quality first, tokens second): P4/Phase 8 dropped outright since lowering effort trades quality for cost, P5 promoted since positive-framing-over-prohibition is what targets guardrails working against output. + +** Split commits.md: 12,800 tokens → 2,342 always-loaded (931f364) + +Craig picked the commits.md split over docs-lifecycle after I checked the latter and found I'd overstated it — =docs-lifecycle.md= scopes to "any project carrying a docs/ tree," a *project-level* condition a glob can't express, and 2 of its 6 trigger points are creation cases a read-triggered path rule misses. Only three rules ever named a concrete extension and all three are already converted, so there is no other clean path-scope candidate. + +The split line is *blast radius*, not size. Stayed always-loaded (1,027 words / ~2,342 tokens): author identity, the no-AI-attribution ban, the generated-document byline rule, the public-artifact content-scope rules, and "If You Catch Yourself." Moved to =publish/SKILL.md= (4,871 words): message format, Voice and Focus, PR description structure, Review and Publish Steps 0-2, the three review shapes, hook authorization, merge strategy, the pre-commit checklist. + +Why that line: if the skill fails to trigger I don't know the flow and have to be told — visible and recoverable. I don't silently commit with AI attribution, because that guard never moved. Only the recoverable half rides the skill-triggering bet, which is what let this ship without waiting on the pilot. + +*Verified by using it.* The skill registered mid-session and I invoked =/publish= to publish its own commit; it loaded with the full flow present. Content conserved and checked rather than assumed: 5,561 words in, 5,898 across both files (delta = frontmatter + the pointer added to the core). Repointed five cross-references in =voice=, =review-code=, =inbox.org=, and =no-approvals.org= that named moved sections. + +Always-loaded rules surface: 44,410 → ~33,950 tokens. Started the day at ~57,800. + +Noted and deliberately not done: =publish/SKILL.md= is a single 4,871-word blob, and both posts argue a long skill should use progressive disclosure internally. It loads on demand now, which is the win worth taking; splitting it further is its own change. + +Also surfaced: the Step 2 =.ai=-tracking heuristic misfires here. It reads tracked =.ai/= as "shared team repo → skip the approval gate," but rulesets tracks =.ai/= as a committed mirror while being a private single-user repo. I kept asking rather than skipping, and flagged it to Craig. + +** testing.md split, gate fixed, first-person directive added (2f45b6e) + +Three changes. *testing.md split* the same way as commits.md — by what has to be resident, not by size. Core keeps TDD-is-default and the three-category requirement (347 words), because those fire *before* any code is written, which is exactly when no skill has been summoned. Everything else → =testing-standards= skill (2,903 words): characterization recipes, per-category detail, property/mutation testing, pyramid, integration rules, naming, test-quality and mocking rules, coverage targets, spike exception, anti-patterns. + +*Approval-gate fix.* The publish flow decided whether to ask by checking whether =.ai/= is tracked, as a proxy for "team repo." Wrong in the direction that matters: rulesets, home, and work all track =.ai/= and all three are private single-user repos, so the rule skipped the gate on Craig's three most-used projects. Now checks whether any remote is on a host other than cjennings.net. Verified both directions including a synthetic GitHub remote. Every current project → gate applies, which matches how the flow has actually been run all session. + +*First-person directive* added to the always-loaded core, at Craig's instruction. One existed for commit bodies/PR prose but it moved into the publish skill, and it never covered code comments at all. Now: everything authored in or about the repo is first person, with one carve-out — a comment describing what the code *does* stays third person, since there the code is the actor. + +Also split =publish/SKILL.md= internally: PR descriptions + the three review shapes → =references/pull-requests.md=, since a plain commit never needs them. SKILL.md 5,012 → 3,888 words. + +*Surface: ~57,800 tokens this morning → ~28,949 always-loaded now* (plus 13,461 path-scoped). Largest remaining: =interaction.md= 3,828, =verification.md= 3,388, =commits.md= core 2,804, =subagents.md= 2,373, =cross-project.md= 2,305. + +Risk recorded rather than buried: testing.md's margin is thinner than commits.md's. If =testing-standards= fails to trigger mid-test-writing I lose the mocking-boundary rules — a quality regression, visible in review, but a real bet where commits.md's moved half was purely procedural. Also moved the TDD rationalization table rather than cutting it; the posts say that kind of over-argument is counterproductive now, but deleting Craig's defense against me skipping TDD is his call. diff --git a/.ai/sessions/2026-07-29-06-36-adversarial-review-flow-and-telegram-fixes.org b/.ai/sessions/2026-07-29-06-36-adversarial-review-flow-and-telegram-fixes.org new file mode 100644 index 0000000..12cbe3d --- /dev/null +++ b/.ai/sessions/2026-07-29-06-36-adversarial-review-flow-and-telegram-fixes.org @@ -0,0 +1,514 @@ +#+TITLE: Session Context — 2026-07-28 +#+AUTHOR: Craig Jennings +#+DATE: 2026-07-28 + +* Summary + +** Active Goal + +Started as inbox triage on a telegram-plugin bug report and became two things: shipping the cross-project fixes that arrived overnight, then designing and dogfooding a mandatory isolated adversarial review before every commit — which immediately found real defects in its own design and in everything filed afterward. + +** Decisions + +- *Merge colliding fixes rather than sequence them.* The parked down-is-launch diff still carried the bad =loadChats= call and cited the segfault gotcha the other fix rewrites. Applying either alone would have shipped a file arguing against itself. +- *"Adversarial", not "hostile"* (Craig). An agent told to attack manufactures findings, so the stance carries a substantiation floor: a finding not substantiated against the diff is dropped. +- *Re-review until the reviewer approves* (Craig's addition, the thing I had missed). Same reviewer continued, not a fresh one — a fresh reviewer can't tell an addressed finding from one that never existed. Bounded at three rounds or first recurrence. +- *Dispatch on every commit*, with the reviewer's own Phase 0 ruling triviality. A floor written as "small" or "mechanical" puts the judgment back with the author, whose judgment is the thing being checked. +- *Pass the requirement source, withhold the rationale.* A ticket is not the author's model; it was written first and by someone else, so it's the only input that can contradict the author's claim. +- *=cycle=, not =pass=, for one sentry loop* (Craig). home proposed =pass=; =sentry.org= already uses it as a numbered noun for the eleven hygiene passes, so =Pass 11= would have collided with =pass 12=. +- *Drop the =references/= link rather than sync the directory.* The four calendar workflows already travel and already carry the recipes. +- *Strip the wrap-org-table task to Verified / Open questions* after its review loop bounded out. The measurements were never what failed. + +** Data Collected / Findings + +- *The telegram bug.* =(telega--loadChats 'main)= sends a bare symbol on the wire; =tdat_plist_value= (=telega-dat.c=) accepts only =(=, =[=, ="=, =-=, digit, =t=, =:=, =n= and calls =assert(false)= on =m=. Verified against telega's source at four points rather than trusting the handoff. Exposure was manual triage only — sentry excludes messengers, so home's eleven overnight cycles never loaded the plugin. +- *=wrap-org-table.el= splits logical rows*, and =lint-org= doesn't merely miss it — it *causes* it. =lint-org.el:424= calls the same broken predicate, so it reports the tool's own correct output as "missing rule between rows — wrap-org-table.el reflows it" when nothing is missing, then reports the corrupted result clean. Idempotence is broken: the tool corrupts its own output on a second run. +- *The isolated reviewer earned its keep on its first four uses*, finding: that withholding the ticket made my claim self-certifying; that my =subagents.md= override reaffirmed the Prompt Contract field that would destroy the isolation; a fourth verdict (=Needs Discussion=) I'd asserted didn't exist; and four successive wrong root-cause analyses on the table bug. +- *rulesets is itself exposed* to the table bug: =todo.org='s four-row attachment-sanitization table. Don't reflow until fixed. +- *Seven =../../= link sites* across four synced workflows resolve only in rulesets. =scripts/lint.sh='s =check_md_links= was built for that class and misses them because it matches markdown syntax only. + +** Files Modified + +Seven commits, all pushed, velox synced after each. =bff0138= merged telegram fixes. =43a4cf7= post-load liveness check. =614e3b1= removed finished working dirs. =ca508a1= filed three handoff findings. =f3f5bfd= the =fire= → =cycle= rename (72 sites plus three that had leaked outside =sentry.org=). =3a933a2= the =references/= analysis. =5999f88= dropped the dead link and deleted the stale file behind it. =ecd5d7b= filed the wrap-org-table bug. + +Rules changed: =publish/SKILL.md= Step 1 rewritten (dispatch contract, four defined verdicts, the loop, bounds), =review-code/SKILL.md= (two levels of dispatch, adversarial contract, re-review mode), =claude-rules/subagents.md= (Isolation Override; Prompt Contract field 2 inverts), and the three unattended callers taught to park. + +** Next Steps + +- *Three of the four items Craig queued are untouched*: the winvm =[#C]= lint defects, the context-engineering rightsizing (needs his four decisions), and the sentry spec deep read (two weeks old). +- *Rule gap found by using the rule*: =Needs Discussion= exits to the user, but nothing says what happens after the user answers — whether the round counter resets. I treated it as a fresh review; that judgment isn't written down. +- *Item 2 is now qualified*: its fix says "run =wrap-org-table.el=", and that tool has a live corruption bug. The specific table is safe, but verify the output rather than trust it. +- Four =[#B]= bugs filed tonight and unstarted: the table splitter, the =../../= links, plus the two carried in. + +KB: promoted 1 / consulted no + +* Session Log + +** 11:55 — Startup + +Ran startup. Rulesets already current, project repo clean and current, =make +install= had nothing new to link, =.ai/= synced from templates. No crash anchor +— previous session (context-engineering rightsizing, 2026-07-27 17:02) wrapped +cleanly. + +Findings: 6 tasks unreviewed >7 days; roam inbox holds 4 items; KB at 108 +=:agent:= nodes with nothing matching this project. Spec-sort and host-identity +probes silent. Language-bundle check silent. + +** 12:05 — Inbox: the telegram segfault root cause + +Four new inbox files from =.emacs.d=, two pairs: a 06:15 intro note + plugin +file, then a 07:21 correction + superseding plugin file. The correction retracts +one secondary claim from the 06:15 write-up (that the "19 of ~50 chats" reading +was truncation caused by the bug — it wasn't; 19 is the real account size, +measured by work at the wire level). Root cause and fix unchanged. + +The proposal: =triage-intake.telegram.org= Step 1 calls =(telega--loadChats +'main)=, and that bare symbol kills =telega-server= outright. + +I verified the whole chain against telega's own source rather than taking the +handoff's word for it (=elpa/telega-20260706.2147/=): + +- =telega--loadChats= (telega-tdlib.el:2190) drops its argument straight into + the request as =:chat_list= with no conversion. Confirmed. +- The C parser =tdat_plist_value= (server/telega-dat.c:466) accepts only =(=, + =[=, ="=, =-=, a digit, =t=, =:=, or =n= to start a value; anything else + prints "Unexpected char '%c' in plist value" and calls =assert(false)=. + =main= starts with =m=. Confirmed, and the accepted-char list in the handoff + is exactly right. +- telega's own callers all pass the object: telega.el:290, telega.el:295, + telega-tdlib-events.el:516. Confirmed. +- The symbol shorthand lives in a different layer — telega-filter.el:472 and + telega-folders.el:99 convert =(eq cl-fspec 'main)= to ='(:@type + "chatListMain")=. Confirmed. + +Every claim holds. Grepped all workflows for other bare-symbol arguments to +=telega--*= wrappers: only the two sites this diff already fixes. + +*The complication I found.* There is already a parked =[#B]= VERIFY (todo.org:136, +from =.emacs.d= 2026-07-24) proposing a different fix to this same file — the +down-is-launch fix, with a prepared diff in +=working/triage-telegram-down-launch/=. Its proposed file still carries the bad +=loadChats= call at its lines 52 and 122, and its third hunk adds prose citing +"tdlib segfaults in native mode (SEGFAULT gotcha below)" — pointing at the very +section this new handoff rewrites to say the crashes were our bug, not tdlib's. +Applying either one alone leaves the file half-right. They need merging, not +sequencing. + +Also: home and work both declare =telegram= in =:TRIAGE_SOURCES:=, so both have +been killing telega-server on every sweep. Work already patched locally and +verified at the wire level. Home has not been told. + +** 11:58 — Staged the batch, closed the loops + +The Stop hook counted the four files still sitting in =inbox/=. The triage was +done; what remained was Craig's merge decision, not mine. So I staged all four +into =working/triage-telegram-segfault-rootcause/= (the 07:21 pair as +=.proposed= + correction note, the 06:15 pair kept as superseded context — its +blast-radius and follow-up sections aren't repeated in the correction). Inbox +back to clean, =inbox-status= rc=0. + +Left =working/triage-telegram-down-launch/= untouched: the parked VERIFY's body +links its =proposed.diff= by path, and moving it would break the link before +Craig has decided anything. If he takes the merge, that consolidates then. + +Replied to =.emacs.d= — confirmed the verification, and told them the one thing +they couldn't see: their own 2026-07-24 parked diff collides with this, both in +the stale =loadChats= call it still carries and in the native-mode prose it adds +citing the gotcha this rewrites. Also declined their suggested bare-symbol lint: +one consumer file, two call sites both fixed, so the stated rule is cheaper than +a checker with a single input. + +Notified home directly with the mechanism and the two-site fix, told it to patch +locally rather than wait on the canonical, and carried the correction forward +explicitly so it doesn't inherit the retracted truncation story. + +Nothing applied to the canonical. That still waits on Craig. + +** 12:10 — Craig picked the merge. Applied and committed. + +Merged both fixes into one version rather than sequencing them. Base was the +segfault-corrected file, then the three parked hunks on top: the down-is-launch +directive, the SCAN-FAILED-only-after-launch-attempted rewording, and =(setq +telega-use-docker t)= restored to the Step 1 code block. + +The reconcile that made merging worth doing. The parked hunk's new comment said +"tdlib segfaults in native mode (SEGFAULT gotcha below)", pointing at the +section the other fix rewrites to say those deaths were our own bad argument. +Left alone the file would have argued against itself. I changed the Step 1 +comment to state plainly that the two are separate concerns (the deaths happened +*in* docker mode, so docker mode is neither a defense against the loadChats bug +nor evidence for itself), and reworded the Quick Reference line from "tdlib +segfaults outside docker mode" to "crashed in native mode (2026-06-09)" with the +same disambiguation. + +That reword also removed a host-identity violation I hadn't gone looking for. +The original asserted "Craig's daemon currently has telega-use-docker nil" — a +mutable machine fact stated as fixed in a synced doc. I checked the actual +default (=telega-customize.el:514=, =defcustom telega-use-docker nil=) and wrote +the durable claim instead. + +Verified: both live call sites use the TL object, the two remaining ='main= +occurrences are inside the gotcha prose describing the bug, lint-org clean on the +changed file, mirror synced, =make test= green before (exit 0) and after (exit +0). + +todo.org: closed the parked =**= VERIFY as =DONE= + =CLOSED:= per todo-format.md +with the merge rationale in the body. Promoted its =***= engine child (SCAN +FAILED must not advance the sentinel) to top-level =**= VERIFY so it doesn't get +buried under a DONE parent. Kept its =:LAST_REVIEWED: 2026-07-24= rather than +stamping today — I moved it and judged it separate, but nobody re-derived its +content, so the older date keeps it honest. + +Review: Approve, no Critical or Important. Two Minor, both surfaced rather than +fixed. The gotcha now advises a post-load =(process-live-p ...)= check that the +Step 1 recipe doesn't actually do, and adding it would extend the recipe past the +two fixes Craig approved. + +Committed =bff0138=. Not pushed — that's a separate confirmation. + +** 12:20 — home replied, and corrected my urgency read + +home accepted, patched both call sites locally, and re-verified the diagnosis +independently rather than trusting it. Useful correction back: home declares +telegram in =:TRIAGE_SOURCES:=, but sentry excludes messengers from triage +intake, so the plugin never loaded on a sentry fire. Eleven overnight fires ran +clean against the broken file. I had assumed the sweeps were affected; the real +exposure is manual triage intake only. + +Told home its stopgap won't be reverted into a broken state — the next rsync +replaces it with canonical content carrying the same fix. On this machine that +lands as soon as its next startup runs, since the rsync reads the local rulesets +working tree. velox needs the push. + +Inbox back to zero. + +** 14:10 — Pushed, and closed the velox gap + +Pushed =1675613..bff0138= to origin after the pre-push reconcile (still 1 ahead, +0 behind). + +=.emacs.d= replied while the push was in flight. It had already verified bff0138 +here, re-run its own workflows rsync, and confirmed the corrected form landed. +It withdrew the bare-symbol lint suggestion, conceded the home omission, and +flagged one real gap: bff0138 was committed but not pushed, so velox stayed +exposed. That was true when written and stale by the time it arrived. + +Checked velox over tailscale (this host is ratio, per =uname -n=). It was 1 +behind / 0 ahead and sync-safe, so I fast-forwarded it through the same +=git-worktree-gate sync-safe= check startup uses. Velox is now at bff0138 and its +workflow file carries the corrected call, with the only bare ='main= occurrences +inside the gotcha prose. Both daily drivers covered. + +Corrected read carried into both replies: the exposure was manual triage intake +only, not the automated sweeps, because sentry excludes messengers. + +** Open follow-ups (surfaced to Craig, not acted on) + +1. The gotcha tells callers to check =(process-live-p (telega-server--proc))= + after a load, but the Step 1 recipe doesn't do it. Now that the corrected call + shouldn't kill the server, that check is what would catch a regression. Left + out deliberately as scope creep past the two approved fixes. +2. Both =working/triage-telegram-*= dirs are completed-task artifacts and want + filing per working-files.md. Revised read after checking: delete both + outright. Every file is tracked (=b19d420= and =bff0138=), so git holds them + permanently and a copy in =assets/= would only duplicate history. Nothing + links to them. + +** 15:00 — Second inbox round: .emacs.d self-correction + winvm lint findings + +=.emacs.d= wrote back to say it had overcorrected on home: it accepted "home was +in the blast radius" and then recorded that home "had been killing telega-server +on every sweep too", which home's own sentry data refutes. It fixed its task +record rather than leaving it. I told it the pattern wasn't one-sided — I made +the same move this morning, estimating home's blast radius instead of measuring +it, and home's data is what corrected me. It also offered the emacs-side half of +a completed-vs-truncated signal, which it has filed as =[#C]=, if the +=process-live-p= recipe change lands. + +=winvm= sent a link-integrity pass with three findings, all reproduced against +the rulesets source rather than only its local copy. I verified all three: + +1. =protocols.org:273= links =references/calendar-reference.org=, but the rsync + set is only =protocols.org=, =workflows/=, =scripts/=. Dead link in every + consuming project. home and =.emacs.d= have no =.ai/references/= at all. +2. =retrospectives/PRINCIPLES.org:38= violates the org-table standard. + =lint-org= confirms, checker =org-table-standard=. +3. =protocols.org= lints 8 mechanical + 19 judgment =misplaced-heading=, all + from Markdown =**bold**= in an org file. 48 bold spans, 14 line-initial. + +The check winvm couldn't run: adding =references/= to the sync brings =--delete= +with it, which would destroy project-owned files there. work is the only project +with a =.ai/references/= and its copy is byte-identical to the source, so nothing +would be lost. That clears the path to sync-it over drop-the-link. + +One refinement back to winvm on finding 3: the 8 mechanical hits are would-fix, +and the 14 line-initial bold spans are exactly what =lint-org --fix= would +rewrite without knowing they're emphasis rather than headings. So that half is +not safe to run mechanically even though the count suggests it is. + +Filed as =[#B] :bug:= (the dead link, Minor x every-project-every-sync = P2) and +=[#C] :chore:= (the two cosmetic defects, P3), both stamped =:LAST_REVIEWED:= +today since I graded them today. Verified todo.org's lint counts are unchanged +from the pre-edit baseline (mechanical=2, judgment=12, both pre-existing and +already in =inbox/lint-followups.org=). + +Inbox back to zero. todo.org is left uncommitted deliberately — Craig has a +pending decision that will likely touch it again, so batching beats a churn +commit. + +** 18:45 — Craig took both follow-ups. Liveness check staged. + +Added the liveness check to the Step 1 load call. It now returns ='server-died= +instead of an unconditional ='loaded=, and new prose routes that into the +existing SCAN FAILED definition rather than inventing a category: a server that +dies during load leaves a thin hash, which reads exactly like a quiet account, +which is the same false all-clear the down/not-loaded rule already prevents. + +Self-review caught a real defect in my own first draft. I called +=(telega-server-live-p)= bare, but Step 0 guards the same predicate with +=fboundp= because telega may not be loaded. A launch that failed outright would +have signalled void-function instead of returning the clean contract. Added the +guard, matching Step 0's idiom. Verified the predicate is exactly the +=process-live-p= expression the gotcha names (=telega-server.el:221=). + +Verified: parens balance at depth 0, lint-org 0/0, mirror identical, =make test= +green (exit 0) on the final state. + +Not committed — waiting on the approval gate. + +** 18:48 — Third inbox round + +=.emacs.d= sent a closing FYI marked no-action, agreeing my framing of the shared +failure (blast radius estimated rather than measured) named the trigger rather +than the failure. Deleted without reply, since replying to "nothing owed back" +is noise. + +home proposed renaming sentry.org's noun-sense "fire" to "pass", after Craig read +its "nine fires" as nine emergencies: "I assume you mean nine crises, not nine +loop cycles and I begin to get scared." The problem is real, well-evidenced, and +reaches Craig directly through digest headings. + +But the proposed term is wrong, and the reason home gave for it is the +disqualifier. =sentry.org= already uses "pass" as a precise numbered noun — the +pass list, the Pass Runner, "eleven finding/hygiene passes", "pass 12". With +exactly eleven hygiene passes, home's proposed =** Pass 11= heading collides with +an existing referent. That trades a term Craig misreads as urgent for one that is +genuinely ambiguous. + +Counter-proposed *cycle*: zero occurrences in the file, and Craig's own word in +the quote home cited. Checked and rejected "sweep" (3 uses) and "run" (used as a +noun). Filed =[#C] :chore:= with the grading and the collision analysis; replied +to home with the counter-proposal. + +** 18:50 — Three commits, and the collision confirmed from live evidence + +Craig approved both follow-ups and the =cycle= term. Three commits: + +- =43a4cf7= the liveness check. +- =614e3b1= removed both telegram working dirs. Filing by deletion, since every + file was already in git via =b19d420= and =bff0138= and an =assets/= copy would + only duplicate history. +- =ca508a1= filed the three handoff findings with their gradings. + +home wrote back confirming the "pass" collision was real, and that it had already +walked into it: its anchor now carries =** Pass 11= meaning the eleventh cycle, +three lines from =pass 12 (solo-task implementation)= meaning the twelfth item in +the pass list. Same file, two referents, introduced by its own normalization an +hour earlier. It found that in live evidence faster than reading the file would +have caught it. + +It was blocked on Craig's confirmation and had written a memory saying "pass", so +I sent the confirmation immediately. The memory was the urgent half — a stale one +teaches every future home session the ambiguity, where the anchor is one file. + +Recording Craig's approval flipped the sentry task to =:solo:=. The term was the +only judgment it carried, and the completion check is objective, so it can ride a +backlog run rather than waiting for someone to touch =sentry.org=. + +Pushed =bff0138..ca508a1=, velox fast-forwarded to match. + +** 19:45 — The cycle rename, and the leak home's scope missed + +home did its side first: renormalized its anchor by restoring the +pre-normalization backup and re-running fire→cycle from clean, rather than +reverse-mapping pass→cycle. That was the right call — reverse-mapping would have +needed a judgment on every instance to separate its own conversions from genuine +pass-list references, where re-running from clean makes it structural. It also +corrected its memory and handed the canonical back. + +Did the canonical rename with a script rather than by eye: protect the verb sites +by explicit pattern, assert zero unclassified =-ed/-ing= forms survive, then +substitute. 72 noun instances converted, 4 verb sites untouched (=/loop= fires +again, two "fires on approval", "record of what fired"). + +*The leak home's scope missed.* The term wasn't confined to =sentry.org=. +=wrap-it-up.org= said "a crashed fire", and =todo-cleanup.el= and its test both +said "every sentry fire" — all three naming a sentry cycle. Renaming only +=sentry.org= would have split the vocabulary across files. Found by grepping +every file that mentions sentry, then re-grepping without a context window after +the first pass truncated short-line matches and hid them. + +Verified: exactly 3 verb instances left in sentry.org, no placeholder leaked, the +digest commit template now reads =<date> <time> cycle=, capitalized plurals +handled, lint 0/0 on sentry.org, suite green (exit 0 — load-bearing here, since +=todo-cleanup.el= and its test are under test). The two =wrap-it-up.org= lint +findings are pre-existing and identical at HEAD. + +Committed =f3f5bfd=, pushed, velox fast-forwarded and verified. Notified home +(with the leak it hadn't seen) and =.emacs.d=. Closed the task =DONE=. + +Four commits this session, all pushed, both daily drivers current, inbox at zero. + +** 20:00 — Roam inbox zero, then the adversarial-review design + +Roam scan: 3 items, 1 claimed (=rulesets:= prefix), 2 unowned gear links left +for Craig. Filed the claimed one, removed it from roam under capture-guard + +roam-write lock, triggered =roam-sync=. A local =.emacs.d= FYI also cleared. + +The claimed item: "code reviews must occur before every commit an agent does, +and they should be hostile reviews from a subagent without the agent's context." + +Craig's decisions: *adversarial* rather than hostile (he took my push-back that +an agent told to attack manufactures findings), plus a requirement I had missed — +a re-review loop that runs until the reviewer approves — and that the rules must +not contradict afterward. Unopposed recommendations I proceeded on: dispatch on +every commit with the reviewer's own gate deciding triviality, and the flow lands +in the =publish= skill. + +Wrote it into three files: =publish/SKILL.md= Step 1 (dispatch contract, +adversarial-with-substantiation, the loop, bounds), =review-code/SKILL.md= (the +two levels of dispatch, the adversarial contract, re-review mode), and +=claude-rules/subagents.md= (a new Isolation Override section, since three +separate size rules there said don't dispatch small work). + +** 20:30 — Dogfooded it, and the reviewer found nine things + +Ran the new flow on its own diff: dispatched an isolated adversarial reviewer +with the diff plus a one-line claim, withholding everything else. It returned +REQUEST CHANGES with seven Important and two Minor, every one substantiated. I +checked each against the files rather than accepting them, and all nine were +real: + +1. =Skipped= from Phase 0 is not =Approve=, so trivial diffs dead-ended at a gate + with no defined pass. +2. =no-approvals.org= line 73 (the actual execution step) still described the old + inline unbounded flow; I had only updated the preamble at line 49. +3. =work-the-backlog.org= and =sentry.org= — the unattended callers — had no + receiver for "stop and surface to the user". The speedrun routes to + work-the-backlog, not the file I updated. +4. The Step 2 exception still said the review runs "when it applies", which my + rewrite had made false. +5. *The sharpest one.* Withholding the ticket/plan makes the author's claim + self-certifying and strands =review-code='s Intent-vs-Delivery criterion — the + one aimed at exactly the inherited-scope error this gate exists to catch. A + ticket is not the author's model; it is the independent record of what was + asked. I had not considered this. +6. The loop turned on the verdict token, so a single Minor could burn all three + rounds and escalate. +7. My override said it "doesn't relax the Prompt Contract" while field 2 of that + contract says paste your context verbatim — which would destroy the isolation + the whole change is built on. +8. todo.org carried an unrelated =references/= rewrite, and the new task body + listed as open the questions the same commit answered. +9. =subagents.md= still says subagent output is a claim to verify, unreconciled + with "approval is the reviewer's to give". + +All nine fixed. The =references/= hunk is split out as =3a933a2=. Round 2 sent +back to the same reviewer, which is the loop working as designed. + +** 21:30 — The loop closed at three rounds + +Round 2 (three findings): =review-code='s adversarial contract still said two +inputs, so the round-1 fix landed in =publish= but not in the text the reviewer +reads — the two files disagreed at the one seam the change was about. A +count/list regression my own fix introduced ("exactly two things" over a +three-item list). And a fourth verdict I had missed entirely: =review-code= +emits =Needs Discussion=, which is exactly what an adversarial reviewer reaches +for on an architectural objection, and the flow had no handling for it. + +Fixing =Needs Discussion= reproduced round 1's finding 3 one level down, which I +caught myself: all four unattended parking clauses keyed on "the loop hits its +bound", and a first-round =Needs Discussion= is not a bound hit. Rewrote all four +to trigger on "the review can't reach approval" with the three causes named, and +asked the reviewer to verify that independently rather than take it from me. + +Round 3: APPROVE, with one Minor — a recurrence of the count/list mismatch, since +my fourth-verdict fix left the lead-in saying "three outcomes" above four +bullets. Fixed the numeral. The committed diff therefore differs from the +approved one by exactly that word, which the flow's own Minor-only rule permits +rather than spending a fourth round. + +The reviewer also verified things I had not asked about and would not have +checked: that =failed= is already a legal outcome slug in work-the-backlog's +metrics table, that the three workflow mirrors carry identical blob hashes rather +than merely similar text, and that no fifth verdict token exists anywhere in +=review-code=. It filed one follow-up correctly rather than fixing it in-diff — +=start-work.md= Phase 7 still summarizes the publish flow instead of pointing at +it, and was stale before today. Filed =[#C] :chore:solo:=. + +Convergence shape across the three rounds: nine findings, three, one Minor. The +residue in later rounds was integration error from the previous round's fixes +rather than new design problems, which is the shape the bound is calibrated for. + +Committed =8062460=, pushed, velox fast-forwarded and verified. + +Six commits this session, all pushed, both daily drivers current, inbox at zero, +tree clean. + +** 2026-07-29 — Walking the remaining items, and a long lesson + +*Item 1, the =references/= dead link* (=5999f88=). Craig picked drop-the-link. +The adversarial review returned =Needs Discussion= — the fourth verdict, on its +first real use — and widened the fix twice, both correctly. My replacement prose +said credentials "live in the rulesets repo" without naming a file, which would +have sent readers to =calendar-reference.org=, whose three paths had been dead +since May. Now names =mcp/README.org=. And the file itself was orphaned by the +link removal, so both copies and the empty =references/= dirs are gone. Round 2 +approved with three Low findings, all against the task record: my count was wrong +(seven sites, not five) and =scripts/lint.sh='s =check_md_links= already exists +for that class, missing them only because it matches markdown syntax. + +*Rule gap found by using the rule.* =Needs Discussion= exits to the user, but I +never wrote what happens after the user answers. Treated it as a fresh review on +the reasoning that Craig adjudicated and the scope changed. Flagged to Craig; not +yet written into the skill. + +*The wrap-org-table bug* (=ecd5d7b=). work reported that the tool splits a logical +row and lint passes the result. Everything I *measured* held. Everything I +*inferred* on top was refuted, four times: + +1. Root cause "absence of rules in the input" — refuted by the double-run repro + (the tool corrupts its own correct, rule-delimited output). +2. "Tested and killed the empty-cell hypothesis" — the fixture was confounded. + With no hlines the code short-circuits at =:184= before the predicate is + reached, so I varied the empty cell while the path that reads it was switched + off, got a negative, and wrote it down as settled. +3. "The reporter's row-below observation discriminates between the paths" — it + doesn't; both produce that signature. Claimed twice. +4. "A static scan can't see primary-path exposure, needs simulation" — wrong, and + worse, I sent it to work, who built on it. Then my *corrected* advice (run the + predicate over rule-delimited groups) was also wrong: work implemented it and + showed it can't discriminate at any threshold, with worked examples where the + same structural signature has opposite correct verdicts. + +Three corrections sent to work, plus a fourth acknowledging their disproof. The +review loop *bounded out* at three rounds — the first bound-out under the new +rule, working as designed. Craig adjudicated by stripping the task to Verified / +Two-fixes-that-work / Open-questions, which is the right shape: the measurements +were never the problem. + +The fix that survived is work's read, not mine: check idempotence (reflow twice, +diff) rather than build a detector. It's true by construction and needs nobody to +decide what a group means. + +*The lesson, stated plainly.* Every refutation across three rounds landed on +inference, never on a measurement. I ran experiments and then over-read them, +repeatedly, at full confidence. work — after I'd sent them three wrong analyses — +labelled their own uncertain number as a floor on a population they couldn't +cleanly define, unprompted. That discipline is the thing to copy. + +I also found the 2026-07-27 note where I'd already observed this exact failure +and left it in a session summary instead of filing it. work's framing: a correct +observation recorded and then read as fine is the same failure as a green check +on a corrupted table. diff --git a/.ai/sessions/2026-07-29-14-29-helper-1055-launch-pilot-idle.org b/.ai/sessions/2026-07-29-14-29-helper-1055-launch-pilot-idle.org new file mode 100644 index 0000000..76e856b --- /dev/null +++ b/.ai/sessions/2026-07-29-14-29-helper-1055-launch-pilot-idle.org @@ -0,0 +1,62 @@ +helper-1055 +#+TITLE: Helper Session — helper-1055 +#+AUTHOR: Craig Jennings +#+DATE: 2026-07-29 + +* Summary + +Closed out by the primary session on 2026-07-31 at Craig's direction, rather +than by this helper itself. It was launched as the live pilot of =ai --helper=, +was never given work, and idled from 14:29 on 2026-07-29 onward. + +** Active Goal + +Serve as the first live helper instance in rulesets, validating the =ai --helper= +launch path end to end against a running primary. + +** Decisions + +None. This session made no decisions and was asked for none. + +** Data Collected / Findings + +The helper launch path works. Every step of the contract's light startup +executed as designed: the launcher-exported =AI_AGENT_ID=helper-1055= was +adopted rather than self-assigned, =helper-mode.org= was read as the role +contract, and every primary-only action was skipped — no Phase A.0 pulls, no +=make install=, no =.ai/= rsync, no inbox processing, no git mutation. + +The roster resolved correctly from inside the helper: one other live agent (pid +3707800) in the same project. Anchors did not collide — the primary stayed on +the unscoped =session-context.org= while this session created +=.ai/session-context.d/= and wrote here. + +** Files Modified + +Only this file. The helper touched nothing else, which is itself the finding: +the contract's read/write tiers held with no enforcement beyond the instruction. + +** Next Steps + +None for this session. The unbuilt pieces it surfaced — startup's roster check +and the live-helper gate on file-wide hygiene passes — are recorded in +=helper-mode.org='s Status section and in the primary's session record. + +KB: promoted 0 / consulted no + +* Session Log + +** 2026-07-29 Wed @ 14:29 CDT — Helper light startup + +Launched as a helper into rulesets with =AI_AGENT_ID=helper-1055= already +exported, so I adopted that id rather than self-assigning. Read +=.ai/workflows/helper-mode.org= (the role contract) and =.ai/protocols.org=. +Skipped everything primary-only: no Phase A.0 pulls, no =make install=, no +=.ai/= rsync, no inbox processing, no git mutation. + +Roster confirms I am not alone — one other live agent, pid 3707800, cwd +=/home/cjennings/code/rulesets=. That primary is anchored on the unscoped +=.ai/session-context.org= (last written 10:46 today), so our anchors don't +collide. =.ai/session-context.d/= didn't exist; I created it for this file. + +Awaiting the work Craig spawned this helper for. diff --git a/.ai/sessions/2026-07-31-06-32-helper-agents-mcp-scoping-and-sync-extraction.org b/.ai/sessions/2026-07-31-06-32-helper-agents-mcp-scoping-and-sync-extraction.org new file mode 100644 index 0000000..e2c5903 --- /dev/null +++ b/.ai/sessions/2026-07-31-06-32-helper-agents-mcp-scoping-and-sync-extraction.org @@ -0,0 +1,656 @@ +#+TITLE: Session Context — 2026-07-29 +#+AUTHOR: Craig Jennings + +* Summary + +** Active Goal + +Started as Craig's question about running a second helper agent in one project +for "dogpiling" bugs, and became four arcs: building and piloting the helper +launcher, prototyping worktree-based branch isolation, an MCP account-binding +and CUI investigation, and finally a propagation incident that my own +uncommitted file had been causing all day. + +** Decisions + +- *Linked worktrees, not bare, and the writer gets the isolation.* A bare layout + moves the path that project discovery, the roster's cwd match, =inbox-send= + resolution and =make install= all key on. Craig's framing pinned the diagnoser + to main; inverted it, because the read-only agent needs no isolation and the + committer does. +- *Port work's sentry corrections rather than apply their file.* Both copies + predated =f3f5bfd= and would have reverted the =fire= → =cycle= rename the day + after it landed. +- *Hold sentry's pass 3 at the mail/messenger exclusion* rather than take the + read-everything change. The =[#A]= account-binding guard is still an unapplied + prepared diff, and a category exclusion is the only thing keeping that hazard + unreachable meanwhile. Craig then reframed it further: each project declares + its own channels, so a blanket rule in either direction is the wrong shape. +- *Extraction before guard changes.* The sync is untested inline bash running in + every project's every session, and both intended fixes modify exactly that. +- *=--force= and a cache caveat on the recovery command*, after the reviewer + checked =audit.sh= and found it skips dirty tracked projects and carries none + of the =--exclude= flags. + +** Data Collected / Findings + +- *=ai --helper= shipped and piloted live* (=84bd121=). The roster excludes its + caller's own ancestry, so it must be run from a separate terminal — from + inside an agent session it silently downgrades to a second primary. +- *=google-keep= was broken, not absent.* keep-mcp 0.3.1 imports FastMCP from + =mcp.server.fastmcp=, which =mcp= 2.0.0 removed, so the server died at import + and every client saw connected-with-no-tools. Pinned =mcp<2=; 23 tools + including =pin_note= and =set_note_color=, so the whole nag-note spec + automates and home's manual workaround is unnecessary. +- *Every MCP server is registered globally*, so =slack-deepsat=, + =google-docs-work= and =linear= are callable from every project. The + =:TRIAGE_SOURCES:= declaration governs one consumer while the exposure sits at + the registry. +- *The claude.ai connectors were live despite being "disabled"*, and probing + showed them bound to the *personal* account — which contradicts the =[#A]= + task's premise that =mcp__claude_ai_Gmail= is work-bound. I carried home's + binding claim forward without checking it, the same error I had caught work + making that morning. +- *My uncommitted =sentry.org= blocked template propagation for a full day.* + Five workflow files went stale in =.emacs.d= alone; two were my own commits + from that morning. Then I re-created the identical condition six hours after + diagnosing it, which is the argument that the guard punishes ordinary WIP with + a silent project-wide outage. +- *Two review rounds each found a real defect in my own work*: an =AI_AGENT_ID= + interpolated unquoted into the pane's command line, and a characterization + test that provably tested nothing (mutation-proven — deleting the flags it + guarded left the suite green). + +** Files Modified + +- =84bd121= =feat(ai): add --helper for a second session in a live project= — + launcher, wrap-up Step 0 helper branch, doc corrections, 30 tests. Pushed. +- =f571057= =refactor(startup): extract the template sync into a tested script= — + =sync-templates= plus 15 characterization tests. Pushed. +- =~/.claude.json=: =google-keep= re-registered with =mcp<2= (ratio only; velox + has no entry at all). +- =stash@{0}=: the sentry CronCreate port, held pending the declaration spec. +- =working/=: four parked handoff sets (sentry arming, triage declaration, sync + model, nag-event vocabulary). +- Worktree =~/code/rulesets-wrap-org-table= on =fix/wrap-org-table=, with a + fixer session live in it. + +** Next Steps + +Sentry: the stashed port, the per-project declaration model for both channels +and passes (Craig's reframe — work skips personal, home skips work, =.emacs.d= +skips both), the pass inventory and its gaps, and the "one more thing" he +mentioned and never got to say. + +Sync: steps 2 through 4 — narrow the dirty guard per path, add the last-synced +manifest, and write work's line into =cross-project.md=. The manifest is the +primary fix, not the narrowing: =.emacs.d='s five-file measurement showed silent +drift is the ordinary case and the loud failure the exception. + +Also open: scope the five work-bound MCP servers to work-local; velox needs the +Keep token and the same scoping; home needs telling their Keep caveat was wrong; +the nag-event rule needs its corrections before landing; and the =[#A]= +account-binding task may rest on a wrong premise. + +KB: promoted 0 / consulted no + +* Session Log + +** 2026-07-29 10:25 — Startup + +Ran startup.org. rulesets already current, project tree clean at 73e8c01, .ai/ +synced from templates, nothing new to link, no language-bundle drift. No +session-context.org present, so the 06:36 session wrapped cleanly. Inbox has 0 +pending handoffs (lint-followups.org is the standing lint queue, refreshed by +last night's commit — 16 judgment items). Roam inbox 2 items, both unrelated +product captures. Staleness: 6 top-level tasks unreviewed >7 days. Surfaced the +two active reminders (context-engineering rightsizing; the two-week-old sentry +spec read). + +** 2026-07-29 10:30 — Helper-agent question: what's actually live + +Craig asked whether a second helper agent in the same project is in place, for a +dogpile scenario: one agent reads code on main, diagnoses, files Linear bugs; +the other branches, fixes, and queues PRs. + +Investigated rather than answering from the todo body. Findings: + +- Shipped and working: =.ai/scripts/agent-roster= (detection), =helper-mode.org= + (the role contract), and the =AI_AGENT_ID= + =session-context.d/= split. +- Not shipped: =ai --helper=. Verified directly — the launcher's option parser + handles only =-h/--help=, =--runtime=, =--print-launch=, =--print-runtimes=, + =--attach=. No helper flag exists. +- Also not shipped: startup's roster auto-routing branch, the wrap-it-up helper + branch, the hygiene-pass live-helper gate. helper-mode.org's own Status + section says the wiring is behind the three-ring gate and not yet live; the + manual "you are a helper" instruction is the only live adoption path. + +The more important finding is that Craig's scenario doesn't fit helper mode as +designed, for a reason orthogonal to the missing wiring: two sessions in one +clone share one working tree and one HEAD. The diagnoser cannot read main while +the fixer works a branch — checkout is global to the clone. Helper mode's +concurrency design is about two Edit writers on one shared org file, not about +branch isolation. Separately, helper-mode.org bans all git mutation for the +helper, which does map his roles correctly (fixer = primary, diagnoser = +helper), but only after the branch problem is solved. + +The unbuilt =[#B] Repository publish-lock for two sessions sharing one clone= +task (todo.org:210) is the same collision from the index side. + +Craig picked: finish the helper wiring first (launcher + wrap-up branch, pilot, +then decide on the startup net), then design the worktree split. He'll keep the +diagnosing agent read-only on code, which closes the write-collision half. I +noted that read-only doesn't make it read =main= — it reads whatever branch the +clone has checked out — and that's what the worktree work fixes. + +** 2026-07-29 11:05 — Slice A + B built: ai --helper and the wrap-up branch + +Green baseline first: =make test= exit 0 before touching anything. + +TDD throughout. Wrote =scripts/tests/ai-launcher-helper.bats= (23 tests) red, +then built against it. The Makefile glob-discovers =scripts/tests/*.bats=, so +the new file is actually covered rather than silently skipped. + +Launcher (=claude-templates/bin/ai=): =--helper <dir>= flag, =_helper_launch_mode= +pure core, =_helper_id= (=helper-<rand4>=), =build_helper_instructions=, +=_resolve_helper_launch= (runs the project's =agent-roster=), and =helper_mode=. +Two deliberate departures from =single_mode=: it never focuses an existing +window (a second session is the whole point, and focusing the primary's window +is the one outcome that can't be what was asked for), and it never runs git prep +(pulls are primary-only). =_order_windows= now matches a =<project>:<id>= helper +window on its colon prefix so it sorts beside its project. + +Roster verdict → decision: exit 1 (others live) → helper; exit 0 (alone) → +warn and fall through to a normal primary launch; exit 2 or script absent → +warn and launch a helper anyway. Unverifiable resolves toward helper on purpose: +a helper that turns out to be alone merely does less, while a primary that turns +out not to be alone runs pulls and rsync under a live session. + +*Real bug caught by shellcheck, not by my tests.* =_resolve_helper_launch= built +the roster path in the same =local= statement that assigned =dir=, which bash +does not support — verified directly: =local a="$1" b="$a/x"= yields =b=/x=. +Every one of my tests passed anyway, because both production callers happen to +have their own =$dir= holding the same value, so the wrong lookup returned the +right answer. Split into two =local= statements and added a test that calls the +function with no =dir= in scope; confirmed it fails against the one-local form +and passes against the fix. + +Wrap-up: new Step 0 helper branch in =wrap-it-up.org= (the old sentry guard +became Step 0.5 — no live cross-references to renumber, checked). A helper +re-runs the roster: primary live → archive its own context file to +=sessions/...-<id>-<description>.org= and stop, no commit/push/hygiene; +orphaned → full wrap, the git ban lifts; roster unavailable → archive-only, +because leaving work uncommitted is recoverable and committing under a live +primary is not. Exit Criteria gained the helper's shorter list. + +Corrected two docs that claimed this doesn't exist: =helper-mode.org='s Status +section and the =protocols.org= helper paragraph. Both now name what is live and +— more usefully — what isn't: startup has no roster check, so a bare =claude= in +a project that already has a session still runs full primary startup; and the +live-helper gate on file-wide hygiene passes is unbuilt, so a primary's +=todo-cleanup=/=lint-org= run can still clobber a helper's scoped edit. + +Verified: =make test= exit 0, 529 passing. =shellcheck= clean on =bin/ai=. +=sync-check.sh= clean (canonical and mirror both updated). Uncommitted. + +** 2026-07-29 14:30 — Live pilot passed; a helper is running now + +Craig ran =ai --helper ~/code/rulesets= from his own terminal. Everything the +slice was supposed to do, it did: roster found this session (pid 3707800) and +returned the helper verdict, id =helper-1055= assigned and exported alongside +=AI_HELPER=1=, window opened as =rulesets:helper-1055= in the =ai= tmux session, +and the helper opener landed verbatim — the helper read =helper-mode.org= as its +first action rather than running startup. + +Two things checked before calling it a pass, because both looked like defects in +the screenshot and neither was: + +- =.ai/session-context.d/= did not exist when the helper first looked. That's + correct — =session-context-path= is a pure resolver and never mkdirs; creating + the file is step 1 of the helper's own light startup. It had already created + =helper-1055.org= (965 bytes) by the time I checked. +- The helper's first Bash call exited 2. Its own =&&= chain broke on the missing + directory; not a wiring fault. + +The helper's anchor is gitignored (=.gitignore:30= =.ai/session-context.d/=), so +a live helper doesn't dirty my tree. My =git status= still shows exactly the +eight files this session changed. + +*Standing constraint while the helper is live:* I must not run any file-wide +hygiene pass — =todo-cleanup.el=, =lint-org.el=, =wrap-org-table.el=. Nothing +enforces that yet (the live-helper gate is the unbuilt piece), so it's on me, +and it matters most at wrap time when the hygiene step runs by default. + +** 2026-07-29 14:45 — Worktree prototype: the fixer checkout + +Craig's design question: bare worktree so each agent gets its own branch? +Recommended linked worktrees off the existing clone, not bare — a bare layout +moves the path that =ai='s project discovery, =agent-roster='s cwd match, +=inbox-send='s basename resolution, and =make install= all key on, and buys +nothing over a linked worktree. Also recommended inverting his role assignment: +the *writer* needs the isolation, not the reader, so the read-only diagnoser +stays here as the helper and the fixer gets the worktree. + +Created =~/code/rulesets-wrap-org-table= on branch =fix/wrap-org-table= off +73e8c01. My eight uncommitted files stay in this checkout, which is what a fix +branch should look like. + +Verified in the worktree: =.ai/protocols.org= and =.ai/scripts/= present (this +project tracks =.ai/= — 192 files), no session anchor (gitignored, so the fixer +gets a fresh one), the launcher accepts it as a project, HEAD on the new branch, +clean status. + +*Correction to what I told Craig.* I said the worktree's =inbox/= would be empty +because handoffs are untracked. Wrong mechanism: =inbox/lint-followups.org= is +tracked (73e8c01 committed it), so it *does* appear in the worktree. The +conclusion holds for a different reason — =inbox-status= reports 0 pending in +both checkouts, so neither session tries to process it. + +*Scope limit worth naming:* rulesets has no Linear and no GitHub remote, so this +prototype exercises the two-agents-two-branches mechanics but not the +file-a-Linear-bug or open-a-PR half of the scenario. Those live in the work +project. + +** 2026-07-30 — Publish flow: the isolated review earned its keep again + +Step 0 reconcile clean (0/0). Remote is =cjennings.net= only, so the approval +gate applies. Staged eight files and dispatched the adversarial reviewer with +the diff, a one-line claim, and the todo.org task body as the requirement +source — withholding my reasoning, per the Isolation Override. + +Verdict: *Request Changes*, three Important. All three were real, and the first +is the kind of defect the isolation exists to catch — it was invisible in my own +model because I wrote the snippet believing it did what I meant. + +1. *The roster call in my new Step 0 omitted the project root.* =agent-roster= + defaults to =$PWD= and keeps only agents at or inside that root, so a helper + whose shell sits in a subdirectory would not see a primary at the root. That + reports "alone", which my own bullet list reads as *orphaned* — the one + branch that commits and pushes. I had written the sentence calling that the + unrecoverable outcome, and then wrote the call that produces it. Verified + empirically: from =scripts/= the old form was worse than the reviewer said — + the =[ -x .ai/scripts/agent-roster ]= test itself fails there, so it never ran + the roster at all and =$?= was the failed test's 1. Now resolves the root with + =git rev-parse --show-toplevel= and captures rc inside the branch. +2. *helper-mode.org still listed startup's roster check as a live route* in + "When to Use This Workflow" while my new Status block said it doesn't exist. + The stale claim sat above the fold, in the section a session reads to decide + whether it is a helper. Now two routes, with the gap stated inline. +3. *=AI_AGENT_ID= was honored unvalidated and interpolated unquoted* into the + command typed into the pane, so an id carrying =;= or a space would run + something else instead of launching the helper. Worse, the override is + *inherited*: a helper's pane exports the id, so =ai --helper= from inside a + helper reuses the parent's — two agents on one context file, the exact + lost-update shape the contract exists to prevent. Added =_sanitize_agent_id= + and =_resolve_helper_id= (sanitize, then mint fresh when that id's context + file already exists) plus four tests. + +Plus four cheap Minors: the help text claimed the fallback skips git prep (it +doesn't), the rc capture above, =$((RANDOM % 65536))= was a no-op on bash's +15-bit RANDOM, and the help now warns that the roster excludes its caller's +ancestry. + +*My own fix had a bug my own test passed anyway.* The first =_sanitize_agent_id= +used =printf '%s\n'= before =tr -c=, so tr translated the trailing newline into +an underscore and every id gained a trailing =_=. The space test asserted a +substring, which "helper_beef_" satisfies. Caught it only because two other +tests failed. Fixed both the sanitizer and the assertion, which is now anchored +on the following space. + +=make test= exit 0, 532 passing. shellcheck clean. sync-check clean. Sent back +to the same reviewer for round 2; not committed. + +Deliberately not fixed: finding 8, a parked +=working/working-dir-orphan-check/wrap-it-up.org.proposed= still carrying the +old "Step 0: Refuse if sentry is live". Pre-existing, and applying it later +would silently revert this work — surfacing to Craig rather than editing a +parked proposal. + +** 2026-07-30 — Committed 84bd121 + +Craig approved the drafted message. Committed =84bd121= on main, 8 files, 646 +insertions. Author =Craig Jennings <c@cjennings.net>=, no attribution. The +pre-commit hook's sync-check passed, so canonical and mirror agree. Tracked tree +clean; the two work handoffs remain as untracked inbox deliveries. Unpushed — +push is its own confirmation. + +** 2026-07-31 — Extraction committed; propagation unblocked + +Committed the extraction after two review rounds. Synced paths verified clean, +so template propagation is unblocked for every project's next startup. + +*Round 1 found a test of mine that provably tested nothing.* The pycache +exclusion test's fixture had no =.gitignore=, so the cache files read as +untracked, guard one fired, the sync never ran, and every "this didn't arrive" +assertion was satisfied by nothing arriving. The reviewer proved it by deleting +all three =--exclude= flags and watching the suite stay green. Fixed by +committing a =.gitignore= into the fixture and asserting the sync *ran* before +asserting what it skipped; re-ran the mutation both ways to confirm it now +bites. + +It also caught my fallback naming a remedy that cannot happen ("the next +successful sync installs it" — the fallback runs *instead of* the sync, so there +is no next one) and found the real out-of-band recovery in =audit.sh=, which I +had not looked for. + +*My own fix for the third finding was wrong on the first attempt.* The +false-success test deleted the canonical inside the live fixture repo, which +registered as staged deletions and tripped guard one — so it exercised the skip +path while claiming to test false success. It failed, which is how I caught it. +Now points =SYNC_RULESETS_DIR= at a nonexistent path. + +Round 2: Approve. The reviewer re-ran the 16-scenario differential +independently, killed every mutant it aimed at the suite including round 1's +survivor, and verified the =audit.sh --apply --force= recovery command actually +does what the message claims. Three Minors, all closed: =--force= added (audit +skips a dirty tracked project without it), the pycache caveat on that recovery +path documented, and the false-success test's negative assertion moved onto a +file that does arrive on a real sync. + +=make test= exit 0, 551 passing. Left uncommitted on purpose: the four parked +handoff directories under =working/=, which want their own commit and do not +block the sync guard. + +** 2026-07-31 — Step one: sync extracted from startup.org and characterized + +Green baseline first (536, exit 0), then extracted the Phase A sync block into +=claude-templates/.ai/scripts/sync-templates=. Faithful extraction — the rough +edges are preserved and characterized rather than fixed in passing, because a +behavior change smuggled into an extraction is unreviewable. + +Proved it faithful *differentially* rather than by reading: ran the old inline +block and the new script against identical fixtures, clean and dirty, and +compared both stdout and a hash of the resulting tree. Byte-identical in both +cases. + +14 characterization tests in =scripts/tests/sync-templates.bats=, glob-discovered +so the gate actually sees them. Two of them pin the incident directly: + +- "ONE dirty file blocks ALL THREE rsyncs" — the 2026-07-30 blast radius in one + assertion. The narrowing change lands by making this test fail on purpose. +- "a locally-edited template is silently overwritten, with no record kept" — + work's regression, pinned. Asserts the output is indistinguishable from an + ordinary sync, that no backup exists, and that nothing anywhere says a local + fix was destroyed. + +=startup.org= now calls the script, with a fallback that *announces* a skip +rather than performing a silent one. First draft of that fallback's prose was +wrong — I wrote that a pre-extraction project "cannot sync itself out of that +state", which is false: the old inline block delivers both the script and the +new startup.org together, so the ordinary rollout never hits the fallback. It +covers only a split rsync. Corrected before it shipped. + +Verified: =make test= exit 0, 550 passing (536 + 14). sync-check clean, exec bit +preserved in the mirror. shellcheck flags one SC2001 style note on the =sed= — +inherited verbatim from the inline block, deliberately not "fixed", since that +would be a behavior-adjacent edit inside an extraction commit. + +*And I immediately re-created today's incident.* =startup.org= is now modified +under the synced paths, so template propagation is blocked again as of this +moment. Same shape as the edit that cost a day, six hours after diagnosing it. +The lesson isn't "remember to commit" — it's that the guard punishes an ordinary +work-in-progress state with a silent, project-wide outage, which is the design +flaw the narrowing fixes. Flagged to Craig rather than left sitting. + +** 2026-07-30 18:35 — My dirty tree was blocking template sync for every project + +Three handoffs: =.emacs.d= at 18:20, work at 18:29, =.emacs.d= again at 18:32 +correcting and escalating its own first framing. Craig is seeing "telega server +died" on every triage run, eight =telega-server= SIGSEGVs on ratio today. + +*My fault, and it ran all day.* The startup guard skips all three rsyncs when +anything under the synced template paths is dirty. My uncommitted =sentry.org= +port sat there through the whole sentry discussion, so *no project received any +template update today* — including home, which started fresh at 08:09 after the +telega fix landed and still didn't get it. Verified: =MM +claude-templates/.ai/workflows/sentry.org= was the only dirty synced path. +Stashed it (=stash@{0}=, named), synced paths now clean, propagation unblocked. + +Holding a synced-path edit uncommitted has a cost I did not price. The +discussion was worth having; leaving the file dirty across it was not. + +*The canonical itself is fine* — =.emacs.d= said so and I confirmed: the +=loadChats= fix is in (=(telega--loadChats '(:@type "chatListMain"))=), the +=telega-server-live-p= dead-server signal is present (8 sites), and the +truncation claim work asked about is *already retracted* at :246-251, crediting +work's own 2026-07-28 wire-level disproof. Both of work's content asks were +already satisfied. + +*The systemic finding, which is the real one and is in my area.* Two failure +modes, and the second is worse: + +1. (=.emacs.d='s first framing) A correctness fix to a synced file has no path + to a running session — sync is startup-only. +2. (work's, from experience) The rsync runs =--delete=, so a local patch to a + rulesets-owned file is *silently reverted* at the next startup by whatever + the canonical held at that moment. A project that did everything right — + hit the bug, diagnosed it, patched locally, logged the patch, restarted — + comes back running the broken version with its log still asserting it was + fixed. That is what happened to work, and it is why three projects believed + this was handled for two days. + +=.emacs.d= is right that a freshness check addresses only its own version. +Nothing currently notices the loss at the moment it happens, because that moment +looks routine and successful. + +=84bd121= still unpushed, so velox will not see the helper work. + +** 2026-07-30 17:35 — The CUI exposure is at the MCP registry, not the declaration + +Work replied to the =:TRIAGE_SOURCES:= defect: fixed their side (cmail dropped +with the reason written in, telegram kept deliberately because Kostya and Vrezh +carry real work traffic there, personal-calendar under review for conflict +checks), and widened the requirement with Craig's words — with CUI in play, +work email, calendar and the rest are off limits to *every other* project. The +reverse direction is the one carrying compliance weight: a personal or tooling +project reading work channels is an exposure question, not a tidiness one. + +They also hit the run-time-read trap the hard way: an auto-triage cron armed +twenty minutes earlier had the source list baked into its prompt, so correcting +the declaration did nothing until they re-armed it. Both their spec suggestions +accepted — deny-by-default for work-account sources, and read the declaration at +run time rather than caching it. + +*Then the sweep turned up something bigger than their note assumed.* Every MCP +server is registered *globally*, with no project scoping anywhere: +=slack-deepsat=, =google-docs-work= and =linear= are directly callable from +home, =.emacs.d=, =.dotfiles=, rulesets, and every other project. This session, +in rulesets, has all three available right now. + +So =:TRIAGE_SOURCES:= governs one consumer — which plugins the triage engine +loads — while the exposure sits at the registry. A correct declaration in every +project would not close it. Any deny-by-default rule for work sources has to +reach the MCP registration layer or it is a rule about the front door written +while the side door stands open. + +Not proposing the fix: project-scoping those servers is a real change with real +tradeoffs (several are useful outside work, and the calendar server manages both +accounts in one place). Craig's call, and bigger than the declaration spec. +Replied to work with the sweep and credited the finding to their handoff. + +** 2026-07-30 — google-keep MCP was broken, not absent; fixed on ratio + +Home's handoff claimed the google-keep MCP "shows as a connected server but +exposes no tools", so a note cannot be created, coloured or pinned +programmatically, and recorded a manual wl-copy workaround in the vocabulary +rule. Craig pushed back: he and home were writing to each other through Keep +notes on vacation last month. He was right. + +*Root cause.* The server is registered globally in =~/.claude.json= as =uvx +--from keep-mcp python -m server.cli=, credentials present. It crashes at import +with =ModuleNotFoundError: No module named 'mcp.server.fastmcp'=. keep-mcp 0.3.1 +imports FastMCP from there; uvx resolves =mcp= to 2.0.0, which dropped that +module (confirmed by listing =mcp.server='s submodules — no =fastmcp=). The +process dies instantly, so a client sees connected-with-no-tools. Not a missing +integration; a dependency regression from =mcp= going 2.0. + +*Fix, applied and verified on ratio.* Pin to =mcp<2=. Re-registered through +=claude mcp remove= / =add --scope user= rather than hand-editing +=~/.claude.json=, because the live session owns that file and would clobber a +manual edit. =claude mcp list= now reports =✔ Connected= where it previously +reported =Failed to connect — Connection closed=. Config backed up first. + +*The capability is fuller than the rule assumed.* 23 tools, including +=create_note=, =update_note=, =find=, =pin_note= and =set_note_color=. So the +entire nag-note spec automates — colour and pin included, the two things home +said had to be handed to Craig by hand. The manual workaround comes out of the +rule. + +*Colour caveat.* Keep has 12 fixed colours: White Red Orange Yellow Green Teal +Blue DarkBlue Purple Pink Brown Gray. There is no "burnt orange" — =Orange= is +the match (Keep's Orange swatch renders burnt). + +*Not done, and why.* MCP servers load at session start, so the tools are not +callable in this session — a restart is needed before any note can be written. +And velox has *no* google-keep entry at all, not a broken one, so it needs +first-time registration including the master token. That is a credential moving +between machines, so I stopped and asked rather than pushing it over tailscale. + +The pin is a stopgap. Upstream keep-mcp needs =mcp= 2.x support, worth filing so +the pin does not become permanent and unexplained. + +** 2026-07-30 — Review of the sentry port: Request Changes, two for Craig + +The isolated reviewer returned *Request Changes* on the port. Verified every +factual anchor myself before surfacing, and all of them hold. + +Fixed (my own defects, both in the paragraph whose subject is a mis-stated +mechanism, which is its own lesson): + +- *I fabricated this file's history.* My line 92 said "an earlier version of this + file claimed a detached schedule hits a headless-auth wall". It never did — + =git log -S'headless'= over both copies returns zero commits. I carried work's + self-description across without checking it against the file it was going + into, which is precisely the error I told work they had made. Now says the + file prescribed =/loop= without stating why, and points at + =triage-intake.org=, where the reasoning actually lives. +- Line 89 claimed the first three constraints "were wrong in this file". Two + were simply absent. Now "none of them were recorded here before 2026-07-30". +- Incomplete rename at :61 and :127, which still called sentry's mechanism a + loop after the diff purged that word everywhere else. + +Two that need Craig, both real: + +1. *Sequencing hazard (Critical).* The new pass 3 turns on unattended mail + hygiene — mark-read, star, trash — across every channel. The =[#A]= + account-binding guard that exists because of the 2026-07-23 wrong-inbox + incident is still a *parked* prepared diff: + =working/triage-account-guard/proposed.diff=, and + =triage-intake.personal-gmail.org= has zero account checks. That incident is + exactly this: a sentry triage cycle bound to the work Gmail account instead + of personal, 201 messages, graded =[#A]= on severity alone. Commit =33949c5= + ("exclude mail and messengers") is what made it structurally unreachable, and + this diff removes that protection while the deliberate replacement sits + unapplied. +2. *A third ruling nobody reconciled.* =todo.org:198= records Craig's + *2026-07-27* correction — scan DeepSat work mail and every messenger, + *excluding only personal email*. Work's 2026-07-30 note reverses to "read + everything" and never mentions 07-27. So there are three rulings, and the + newest may have been given without the middle one in view. + +Not committed. Staged and held. + +** 2026-07-30 — Ported work's sentry corrections; inbox cleared + +Craig confirmed he gave work the pass-3 ruling and asked to see the port before +it lands. Ported rather than applied either file, since both reverted yesterday's +=fire= → =cycle= rename (=f3f5bfd=). + +Six changes to =sentry.org=: overview and interval trigger off the loop +language; step 7 rewritten for =CronCreate= with both shapes; Stop Sentry to +=CronList= / =CronDelete=; the lock model noting overlap can't arise under +self-rescheduling; pass 3 to "read everything, send nothing". + +Three things beyond a straight port. Work's constraint list had three items; I +made it five, adding two facts from =CronCreate='s own docs that neither copy +carried — jobs fire only while the session is idle and never mid-query (so a +long cycle delays its own successor without the lock), and the scheduler's +jitter (up to 10% of period, capped 15 min, so an hourly sentry can land six +minutes late and that is not a stall). Also noted =durable= has no effect, since +someone will reach for it on reading that jobs die with the session. + +And I fixed a real defect from yesterday's rename: canonical pass 3 ended "they +never cycle unattended", which had been "never fire unattended" — the rename +caught the verb. Checked the whole file; it was the only one. + +Verified: lint-org 0 mechanical / 0 judgment, sync-check clean, 80 "cycle" and +zero "fire" as a noun. Uncommitted, awaiting Craig. + +Inbox dispositioned per =inbox.org= park: all four handoffs moved to +=working/sentry-arming-correction/= alongside the prepared diff. Inbox back to +zero. + +** 2026-07-30 07:43 — Work's 07:39 correction: pass 3 is about sending, not reading + +Work sent a second pair at 07:39, three minutes after the first and before my +07:40 reply landed. The correction: Craig told them this morning that the +2026-07-21 pass-3 ruling was that sentry must never *send* via mail or +messenger, never about reading. Their revised pass 3 is "read everything, send +nothing" — full triage across every source, with local-state mail hygiene +(mark-read, star, trash) allowed because it emits nothing, and anything outbound +(a send, a Slack or Signal message, a ticket comment or state move, a posted PR +review, a calendar RSVP) queued for morning approval. + +The framing is good and the outbound/local-state line is the right one. But it +is a policy reversal on a synced shared asset, resting on a ruling given in a +session I was not in and cannot verify from here. Asking Craig directly rather +than applying it. + +The rename conflict persists in the corrected copy: 84 "fire" against 1 "cycle". +They sent before my 07:40 reply, so they had not seen it. Replied acknowledging +the supersession, restating the rename finding, and stating both files are held. + +Net: =CronCreate= substance accepted and verified, pass 3 waiting on Craig, +neither file applied. + +** 2026-07-30 07:40 — Inbox: work's sentry.org arming correction + +Two handoffs from work at 07:36: a prose note plus an edited =sentry.org=, +arguing the arming mechanism was documented wrong (=/loop=, justified by a +headless-auth wall) and should be =CronCreate=. + +Shared-asset proposal, so skeptical review rather than silent application. + +*Substance verified and correct.* Checked all three claims against +=CronCreate='s own tool documentation: jobs are session-only and in-memory and +die with the session; recurring jobs auto-expire after seven days with one +final fire; fires run inside the arming session, hence inherited MCP auth. +Their overnight 2026-07-28/29 evidence matches. The off-minute guidance they +added is verbatim from the tool docs, which is a good sign they wrote from the +source rather than from memory. + +*The file is the problem.* Their copy predates =f3f5bfd= (2026-07-29, +"refactor(sentry): call one loop cycle a cycle, not a fire") — Craig's decision, +72 sites. Their version uses "fire" 85 times and "cycle" once; the canonical is +the inverse. Applying it wholesale reverts yesterday's rename the day it landed. +So: port their step 7, Stop Sentry, and overview changes into the canonical's +=cycle= vocabulary. Parked pending Craig — sentry.org is synced to every +project. + +Two facts from the tool docs neither version carries, worth adding in the port: +jobs fire only while the REPL is idle, never mid-query, so a long cycle delays +its successor on its own; and the scheduler adds jitter (up to 10% of period, +capped at 15 min). + +Agreed with their pass-3 catch — they nearly overturned Craig's 2026-07-21 +mail/messenger exclusion by inferring a technical cause for a policy ruling, and +caught themselves. Left as his call. + +Disagreed with their companion note. =triage-intake.org:210= says auth is +inherited because the sweep runs in the live session, and that the wall applies +to a *detached* cron run — still true of a system cron. Narrower than sentry's +claim was, so not wrong, though it does prescribe =/loop= where =CronCreate= +would also work. Smaller follow-up, not folded in. + +Replied to work with all of the above. Not applied. + +** Pilot prerequisites (recorded 14:30) + +Prerequisites for the pilot, learned by testing rather than assuming: the roster +excludes its caller's own process ancestry, so =ai --helper= must be run from a +separate terminal — from inside this session (or via =!=) it can't see me and +silently downgrades to a second primary. And the =ai= script uses a tmux session +named =ai= while Craig's live agents run in =aiv-<project>= from ai-term.el, so +the helper opens in a different session and switches his client. Pre-existing +launcher behavior; the Emacs surface is a separate handoff to =.emacs.d= per the +task. diff --git a/.ai/sessions/2026-07-31-22-43-sync-guard-narrowing-and-standup-scripts.org b/.ai/sessions/2026-07-31-22-43-sync-guard-narrowing-and-standup-scripts.org new file mode 100644 index 0000000..8714a49 --- /dev/null +++ b/.ai/sessions/2026-07-31-22-43-sync-guard-narrowing-and-standup-scripts.org @@ -0,0 +1,142 @@ +#+TITLE: Session Context — 2026-07-31 +#+AUTHOR: Craig Jennings + +* Summary + +** Active Goal + +Answer the propagation question from the 2026-07-30 outage — how do I work in +rulesets without blocking every other project's template sync — then build the +answer. Four inbound handoffs from work preempted it mid-session and were +processed inline before the build resumed. + +** Decisions + +- *Narrowing first, manifest second.* The per-path =--exclude= narrowing is the + direct answer to the question and cost ~60 lines. The last-synced manifest is + the larger fix behind it and stays unbuilt. +- *Withhold rather than block, per file.* A dirty path is excluded from its own + rsync instead of skipping all three for every project. Verified empirically + before building: rsync honors =--exclude= on both sides, so a withheld file is + neither overwritten nor deleted downstream. +- *The behind-upstream guard stays all-or-nothing.* That staleness lives in the + destination, so there is no single source file to narrow to. +- *Accepted work's standup-script proposal with four changes*, the load-bearing + one being that the script is a draft Craig edits at the gate. A topic list + fails safe by forcing him to compose; a wrong script reads fluently enough to + be spoken unchanged. Work agreed this was better than what they sent. + +** Data Collected / Findings + +*The narrowing, shipped as =f69dc22=.* Each dirty path under the synced roots +becomes an =--exclude= on its own rsync. A dirty =protocols.org= skips only its +own single-file transfer. A rename withholds both names, since sweeping the old +copy would delete a file the project still runs mid-rename. The run now names +what it held back. Suite went 15 → 22 tests; six were written red on purpose to +invert the "ONE dirty file blocks ALL THREE rsyncs" characterization. + +*Verified end-to-end against the live checkout*, which is the strongest evidence +here: mid-change, rulesets had two dirty files under the synced paths. The run +propagated 48 workflows and withheld exactly those two, naming them. The same +run under the old guard would have synced nothing. + +*I was wrong about project-workflows shadowing.* I told work their +=.ai/project-workflows/daily-prep.org= would shadow the synced copy and starve +them of updates. Phase 11 says the project file runs as *additional* steps +appended, "not a replacement" — daily-prep composes both. I had generalized from +=protocols.org='s workflow-selection rule, which governs dispatching a *named* +workflow. Their duplication concern was real by a different route and they +handled it with a marked stopgap carrying an explicit delete condition. + +*Known false-success path, still open and still load-bearing:* the success line +prints unconditionally, so a run whose rsyncs all failed still reports a clean +sync. The manifest must not be written from that branch as it stands. + +** Files Modified + +- =claude-templates/.ai/workflows/daily-prep.org= (=a212eeb=) — standup scripts, + Phase 8 blocking gate, generalized worked example. +- =claude-templates/.ai/scripts/sync-templates= + its bats suite (=f69dc22=) — + the narrowing. +- =todo.org=, =.ai/notes.org= (=cb31fd2=) — voice pattern #48 filed, inbox marker. +- =working/sync-model-revert/= (=1c222cb=) — the parked .emacs.d handoff, which + had been sitting untracked against the working-files rule. + +KB: promoted 0 / consulted no + +** Next Steps + +1. *Build the last-synced manifest* — the other half of the propagation fix, and + the one .emacs.d's measurement said matters more, since silent drift is the + ordinary case and the loud crash the exception. Its design constraint is in + =working/sync-model-revert/=: the report must carry the *diff*, not just a + backup path, so a reader can tell in one look whether the canonical already + contains their patch or whether their change was thrown away. Fix the + unconditional success line first or the manifest will stamp success onto a + sync that did nothing. +2. *Voice pattern #48* is filed =[#B]= and fully specified — Craig approved the + =interaction.md= mirror, so both homes get the rule with a cross-reference + line in each, plus #48 into the attestation high-recurrence set. Work's + suggested text needs its em-dashes stripped before it lands. +3. *Process note worth fixing:* every pre-commit review this session ran inline + rather than in an isolated subagent, because of the session's no-Agent-tool + directive. It caught real defects both times, but a self-review is weaker + evidence than an isolated one, and =subagents.md= names this as the standing + isolation-override case. + +Longer queue, unchanged: sentry's stashed =CronCreate= port and the per-project +declaration model, the MCP scoping of five work-bound servers, velox's Keep +token, the nag-event rule corrections, and the =[#A]= account-binding task whose +premise may be wrong. + +* Session Log + +** 2026-07-31 Fri @ 11:24:43 -0500 — flushed + +Craig returned after the 06:32 wrap and asked to flush before taking the +propagation outage. In flight: nothing on disk, tree clean at =cbcd972=. The +work ahead is a design answer, not an edit, so nothing is half-finished. Read +=.emacs.d='s 08:16 handoff and folded its diff-in-the-report point into the +Findings above before clearing, since it changes the manifest design and would +otherwise have to be re-read. + +** 2026-07-31 Fri @ 13:22 -0500 — inbox processed, standup-scripts shipped + +Three handoffs from work arrived mid-session and preempted the sync question. + +Accepted work's standup-brief proposal with four changes and shipped it as +=a212eeb=: generalized their worked example (it carried real names, an +=AWS Secrets Manager= detail, an investor demo and a specific bug into a file +that syncs everywhere), dropped their "exactly None." punctuation change (it +contradicted the Standups section, which already mandates =Blockers: None=), +scoped the gate to *each* standup rather than the day (their phrasing would +have passed the same text under both headers), and added the clause that the +script is a draft I edit at the gate. That last one is the real finding: a +topic list fails safe by forcing me to compose, where a wrong script reads +fluently enough to be spoken unchanged. Work agreed it was better than what +they sent. + +*I was wrong about the fork.* I told work their =.ai/project-workflows/daily-prep.org= +would shadow the synced copy and silently starve them of updates. Phase 11 of +the template says the project file runs as *additional* steps appended, "not a +replacement" — daily-prep composes both, and there is no shadowing. I +generalized from =protocols.org='s workflow-selection rule, which governs +dispatching a *named* workflow, not this composition. Their duplication concern +was real by a different route and they handled it with a marked stopgap +carrying an explicit delete condition. + +Voice pattern #48 (corrective antithesis, "X rather than Y") filed =[#B]=. Two +additions on the task: it belongs in the attestation high-recurrence set +immediately, and the frequency cap needs mirroring into =interaction.md=, +because Craig noticed the pattern in *conversation* and the voice skill only +runs on publish artifacts. + +*Process note:* the Step 1 pre-commit review ran inline rather than in an +isolated subagent, because this session's directive is not to call the Agent +tool unattended. It caught two real defects (a self-contradicting Blockers rule +and an example that undercut it), but a self-review is weaker evidence than an +isolated one. + +*Still open and unanswered:* the sync-narrowing question from the top of the +session. Options and recommendation are in the Summary above; nothing has been +built. diff --git a/.ai/workflows/code-quality.org b/.ai/workflows/code-quality.org index 0481166..3c4ed8f 100644 --- a/.ai/workflows/code-quality.org +++ b/.ai/workflows/code-quality.org @@ -12,7 +12,7 @@ workflow only sequences them and collects the residue. *Behavior-preserving rests on a test net.* The passes below claim to preserve behavior, but a refactor on untested code is a guess, not a preservation. Where the scope has no tests, bring it under a characterization net first -(Normal/Boundary/Error per unit, per =testing.md='s "Adding Tests to Existing +(Normal/Boundary/Error per unit, per the =testing-standards= skill's "Adding Tests to Existing Untested Code") — that net is what turns "behavior-preserving" from an assertion into something the green suite actually verifies across each pass. diff --git a/.ai/workflows/daily-prep.org b/.ai/workflows/daily-prep.org index 3f21214..9f706d1 100644 --- a/.ai/workflows/daily-prep.org +++ b/.ai/workflows/daily-prep.org @@ -130,12 +130,33 @@ Morning Prep is where Craig reads the prep doc, mentally walks the schedule, and The Yesterday / Today / Blockers brief nests *directly under the standup meeting it's reported in* — never in a separate section. Plain section labels, no parenthetical questions in the rendered doc. -- *Blockers is always present.* When there are none, write =Blockers: None= explicitly — silence is ambiguous. +*The brief is a script, not a topic list.* The lines under each label are the words Craig says — complete first-person spoken sentences. Not fragments, not noun phrases, not a "bring these up" list. A topic list makes him compose the sentence live from a cue he wrote the night before and has since forgotten the shape of; a script is readable as-is. "Brief" invites bullets and bullets decay into topics, which is exactly the failure this rule exists to prevent. + +The script is a *draft for Craig to edit at the Phase 8 gate*, never words put in his mouth. That cuts both ways: a topic list forces him to compose and so fails safe, while a wrong script reads fluently enough to be spoken unchanged. So it gets the same gate scrutiny as the priorities. + +- *Blockers is always present.* A real blocker is stated as a full sentence, not a noun phrase. When there are none, write =Blockers: None= explicitly — silence is ambiguous. - *Outcomes, not attendance.* Never "met with <person>" — instead what came out of it: "<person> finished the branch CI/CD work." Never "went to the managers' meeting" — instead the development from it that affects this audience. - *No recurring 1:1s or ceremonies* in briefs — they're not news. - *Match the standup's altitude.* An engineering standup gets engineering-goal material only: what moved the platform or the demo forward — architecture docs, PRs, tracker tickets, partner meetings with use-case implications, integration discussions, security findings, dataset discoveries. It does NOT get: 1:1s, attending other standups, personal-tooling maintenance, profile updates, sending messages or email, meeting prep, booking travel, or interviews with non-engineering candidates. The three questions are really: (a) how have I moved us closer to the engineering goals, (b) what will I work on that moves us closer, (c) what information do I have that might impact the team or its goals. - A business-level (general) standup is different: features finished that leadership wanted, vacation/travel that affects availability or velocity, conference learnings, partner/customer decisions, cross-functional confusion worth clearing up. *Exclude routine maintenance and operational items — PR reviews don't belong here.* Foundational or strategic engineering work does; operations don't. +Worked contrast — the same day's material, written both ways: + +#+begin_example +Topics (the failure mode — a cue list, not a brief): + Bring: the freeze status, since Monday-or-later is the current answer. + The blocked review. The access request. + +Script (what belongs in the doc): + Yesterday: I fixed the bug where the selected region stayed editable + after an edit, and that's up for review along with the dependency + migration. + Today: I'm holding merges to development until the demo actually + happens, which now looks like Monday or later. + Blockers: None — the access request I raised Monday sits with the + platform team now, so it's slowing them rather than me. +#+end_example + (Drafting rules — first-person, deadline precision, recurring-meeting filters, the team-visible test — are in Phase 6.) *** Meetings @@ -315,7 +336,9 @@ Combine session history + the sweep + Day's Priorities + WAITING items into Yest - *Today*: 2-3 items max, from Day's Priorities. Include non-recurring meetings regardless of response status. - *Blockers*: the bar is "did this actually stop me from making progress?" — not "is someone else involved?" Default to under-reporting; Craig adds borderline items at the gate. FYIs come after blockers and stay loose. - *Team-visible filter*: only work that left Craig's local environment — pushed, shared, posted, changed in the tracker, or shifts what the team believes or plans. "If I didn't mention this, would someone make a worse decision or duplicate work?" If no, cut it. -- Readable aloud in under 60 seconds. +- *Write the words, not the topics.* Every line is a complete first-person sentence Craig can read aloud unchanged — see the worked contrast in the template's Standups section. No bare noun phrases, no "bring up X", and no identifier he wouldn't actually say out loud (a ticket key is fine where the team speaks in ticket keys, and wrong where they don't). +- Readable aloud in under 60 seconds — roughly 120-150 words across the three sections. Over budget means cut an item, not compress a sentence back into a fragment. +- *One script per standup.* Two standups on the same day get two separately-drafted scripts, because the altitude rules above admit different material to each. The same text under both headers is a defect, not a shortcut. *** Step 3: Capture learnings @@ -331,6 +354,8 @@ Also assemble the end-of-day block's upcoming-deadlines list: =DEADLINE:= entrie Present the assembled doc and ask whether Craig agrees with the Day's Priorities. If not, work with him to add / remove / substitute priorities and blocks until he confirms. Surface here, in one pass: meeting-goal questions, decline candidates, look-ahead flags, carry-forward decisions, and proposed schedule adjustments. +*Standup-script check (blocking).* The prep is not complete until every standup on that day's calendar carries its own script under its header, in the Phase 6 shape — spoken sentences, =Blockers:= present, altitude-matched. Check each standup individually and present the scripts at this gate for Craig to edit. Vacuous on a day with no standup, which is the common case in projects that hold none. This check exists because Phase 6's prose alone did not hold: on 2026-07-31 a prep wrote topic lists under both standup headers while every rule requiring a script was already on the page. Adding more prose to Phase 6 would not have caught that — the prose is what got skipped, so the requirement has to sit on a gate that blocks. + If the gate produces substantive rework, say so plainly: that's a =todo.org= staleness signal — the file should make Craig's current priorities obvious. Offer a task review. Update mode replaces the gate with a delta summary: what changed and why. @@ -448,3 +473,6 @@ The prep doc is born in =daily-prep/YYYY-MM-DD-daily-prep.org= and never moves; *** 2026-06-11: Full template rewrite — strict three-section doc, two run modes, mandatory priorities gate From Craig's instructive template spec (written 2026-06-10 evening, after reviewing generated preps) plus four refinements from his review of the first new-format prep. The doc is now exactly =* Heads-Up= / =* Day's Priorities= / =* Meetings / Focus Blocks=. Retired: the separate =* Standup Briefs= and =* Upcoming Deadlines= sections (briefs nest under their standup meeting; deadlines live in the end-of-day block), the =* [Day]'s Anchor Tasks= handoff (carry-forward lands directly in the next day's priorities, which are being built in the same sitting), the thin-link convention (entries mirror their todo.org task's heading and carry their own context — links in the body, never the heading), and standup-only mode (a brief refresh is an Update-mode run). New: two run modes (Create, with a MANDATORY end-of-flow priorities review gate whose disagreement signals todo.org staleness; Update, for when the world moves) both preceded by a triage-intake freshness check (no run in the last hour → run one first); event headers are the exact calendar title with ALL content nested under the event; per-event-type content rules (Morning Prep conflict-resolution strategy with drafts pre-written in the doc ready to send, standup altitude matching with =Blockers: None= explicit and operations excluded from business-level briefs, meetings carrying contribute/get/likely-questions with day-before prep blocks for "I don't know" answers and prep docs always =file:=-linked — the lesson of a prep that existed but couldn't be found in the minutes before a meeting that mattered, focus blocks as linked menus created day-before and marked free, lunch floor, the end-of-day "What Kind of Day Has It Been?" block carrying the deadlines list and generating tomorrow's prep); the look-ahead renders one day per line (=Fri 12:= …) with clear days marked =clear=; a requested-metrics Heads-Up slot rendered only when a metric is active (none yet); meetings verified against the live calendar at build and update time. + +*** 2026-07-31: Standup briefs are verbatim scripts, enforced at the Phase 8 gate +A prep wrote =Bring:= topic lists under both standup headers while every rule requiring a Yesterday/Today/Blockers brief was already on the page. The rule existed and was skipped, so the fix is a gate rather than more prose: Phase 8 now blocks until every standup on the day's calendar carries its own script, and the Standups section says plainly that the lines are the words Craig speaks — complete first-person sentences, one script per standup since the altitude rules admit different material to each, roughly 120-150 words for the under-60-seconds target. A worked topics-vs-script contrast sits with the shape rules, because prose decays back into bullets and an example doesn't. The script is a draft Craig edits at the gate, never words put in his mouth: a topic list fails safe by forcing him to compose, where a wrong script reads fluently enough to be spoken unchanged. diff --git a/.ai/workflows/helper-mode.org b/.ai/workflows/helper-mode.org index a6acfa7..b32d574 100644 --- a/.ai/workflows/helper-mode.org +++ b/.ai/workflows/helper-mode.org @@ -12,13 +12,14 @@ The governing fact behind every rule below: the session-context split isolates e * When to Use This Workflow -No operator trigger phrase. A helper reaches this contract one of three ways: +No operator trigger phrase. A helper reaches this contract one of two ways: - The =ai --helper= launcher routes here after the roster confirms a live agent (the deterministic path). -- Startup's roster check finds the session is not alone and routes here instead of running normal startup (the safety net for a raw =claude= launch). - An explicit "you are a helper, follow helper-mode.org" instruction (the manual fallback). -If none of those applies — the roster shows the session is alone — this is a primary session. Run normal [[file:startup.org][startup.org]], not this. +There is deliberately no third way, and the gap matters: *startup does not check the roster*. A bare =claude= launched into a project that already has a live session runs full primary startup — pulls, rsync, inbox processing — without ever reaching this file. That safety net is designed (see Status below) but unbuilt, so nothing catches a raw launch. Use =ai --helper=. + +If neither route applies, this is a primary session. Run normal [[file:startup.org][startup.org]], not this. * Identity @@ -92,10 +93,28 @@ A helper does not run normal startup. It runs a light version: When the helper's work is done: -1. Re-run the roster (=.ai/scripts/agent-roster=) to learn whether a primary is still live. +1. Re-run the roster to learn whether a primary is still live. Pass the project root explicitly — =agent-roster= defaults to =$PWD= and keeps only agents at or inside that root, so calling it from a subdirectory hides a primary sitting at the root and reports "alone": + + #+begin_src bash + root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" + if [ -x "$root/.ai/scripts/agent-roster" ]; then + "$root/.ai/scripts/agent-roster" "$root"; rc=$? + else + rc=2 + fi + echo "roster rc=$rc" + #+end_src + + Read rc as =wrap-it-up.org= Step 0 does: 1 means a primary is still live, 0 means this helper is orphaned, and 2 (or an absent script) means unavailable — which takes the same archive-only path as 1, because leaving work uncommitted is recoverable and committing under a live primary is not. 2. *Primary still live (the normal case):* finalize the Summary in the helper's own =.ai/session-context.d/<id>.org=, archive it to =.ai/sessions/YYYY-MM-DD-HH-MM-<id>-<description>.org=, and stop. Do NOT commit, push, or run hygiene — the primary's next commit picks up the archived file and any scoped edits the helper left in the tree. 3. *Orphaned helper (roster shows the helper is now alone):* the primary already exited, so the helper assumes full closing duties — the git ban lifts because the concurrency that justified it is gone. Commit and push the tree (including the helper's own edits, which would otherwise strand as a dirty tree), per the normal wrap-up flow in [[file:wrap-it-up.org][wrap-it-up.org]]. * Status -Phase 1.5 of the generic-agent-runtime spec. This contract is the canonical home; the spawn paths (=ai --helper=, startup's roster branch) and the [[file:wrap-it-up.org][wrap-it-up.org]] helper branch route here. Those wiring pieces ship behind the spec's bats-then-drills-then-pilot gate and are not yet live; until then, the manual "you are a helper" instruction is how a session adopts this contract. +Phase 1.5 of the generic-agent-runtime spec. This contract is the canonical home; the spawn paths and the [[file:wrap-it-up.org][wrap-it-up.org]] helper branch route here. + +Live now: =ai --helper <project>= (roster check, id assignment, helper opener, its own tmux window), the explicit "you are a helper" instruction, and the wrap-it-up.org Step 0 helper branch. + +Not built yet, and worth knowing because it is the gap you can fall into: *startup has no roster check*. A second session launched as a bare =claude= in a project that already has one runs full primary startup — pulls, rsync, inbox processing — with no idea another agent is live. Until that safety net exists, =ai --helper= is not merely the preferred path, it is the only one that makes a helper without being told. + +Also unbuilt: the live-helper gate that pauses a primary's file-wide hygiene passes (=todo-cleanup.el=, =lint-org.el=, =wrap-org-table.el=) while a helper is mid-edit. Data-integrity rule 1 above describes the intended behavior; nothing enforces it yet, so a primary running hygiene can still clobber a helper's just-written scoped edit. diff --git a/.ai/workflows/no-approvals.org b/.ai/workflows/no-approvals.org index b4c7fcf..6b5c7fa 100644 --- a/.ai/workflows/no-approvals.org +++ b/.ai/workflows/no-approvals.org @@ -46,7 +46,7 @@ The interaction gates that step the workflow back to Craig for an "OK to proceed The engineering-discipline gates protect quality, not Craig's interaction time. They remain in force: -- =/review-code= against the staged diff before every commit. Critical and Important findings still block. Minor findings still surface. No "proceed anyway" override unless Craig has given it explicitly for this batch. +- =/review-code= against the staged diff before every commit, dispatched as an isolated adversarial reviewer per the =publish= skill's Step 1 — no-approvals removes *interaction* gates, never the isolation. Critical and Important findings still block, and the re-review loop still runs to approval. Minor findings still surface. No "proceed anyway" override unless Craig has given it explicitly for this batch. If the review can't reach approval — three rounds, a recurring finding, or a =Needs Discussion= verdict — that is a genuine question: park the item per step 4 and move to the next one rather than committing past a standing finding. - =/voice personal= on every publish artifact (commit messages, PR titles + bodies, PR review comments). The full pattern walk happens. The printed result just doesn't wait for approval. - The full test suite + lint + compile before commit (per =verification.md=). - Fetch-and-reconcile in the =publish= skill, Step 0. @@ -70,7 +70,7 @@ For each item: - Do the work. - Update the Session Log per the rules in =protocols.org=. -- Before any commit: run =/review-code= against the staged diff. Surface Critical and Important findings inline; fix them and re-review until clean. Minor findings show but don't block. +- Before any commit: dispatch the isolated adversarial reviewer per the =publish= skill's Step 1 — never review your own staged diff inline. Surface Critical and Important findings; fix them and send the updated diff back to the *same* reviewer until it approves. Minor findings show but don't block and never earn another round. If the review can't reach approval — three rounds, a finding that recurs after being reported fixed, or a =Needs Discussion= verdict — park the item per step 4 with the standing findings and move on; don't commit past a blocking finding. - Draft the commit message. Run =/voice personal= (the skill, or walk the patterns inline if unavailable). Print the final message inline before committing so the log shows it. - Commit and push. - One-line status between items ("Task X done, on to Y.") so Craig knows what's happening when he checks back in. diff --git a/.ai/workflows/sentry.org b/.ai/workflows/sentry.org index e25ca39..b25fc14 100644 --- a/.ai/workflows/sentry.org +++ b/.ai/workflows/sentry.org @@ -4,11 +4,11 @@ * Overview -Sentry is an interval loop that keeps a project's hygiene current while Craig is away. Each fire walks a fixed list of passes — roam pull, inbox zero, triage (no mail or messengers), todo cleanup, task audit, working-files hygiene, spec board, link integrity, git health, prep freshness, bug and refactor finding, and (opt-in) solo-task implementation — and commits each pass's writing to a throwaway daily branch. Nothing pushes. In the morning Craig reviews the branch, squash-merges what he wants, and deletes it. +Sentry is an interval loop that keeps a project's hygiene current while Craig is away. Each cycle walks a fixed list of passes — roam pull, inbox zero, triage (no mail or messengers), todo cleanup, task audit, working-files hygiene, spec board, link integrity, git health, prep freshness, bug and refactor finding, and (opt-in) solo-task implementation — and commits each pass's writing to a throwaway daily branch. Nothing pushes. In the morning Craig reviews the branch, squash-merges what he wants, and deletes it. The design goal is a project that greets the morning already tidy, with every judgment call and every destructive action parked in an approval queue rather than executed unattended. Sentry does the mechanical sweeping; Craig does the deciding. -This file is the engine. It owns the entry gates, the branch mechanics, the lock model, the per-fire pass runner, the digest and approval queue, the skip semantics, and the stop-sentry shutdown. The =agent-lock= helper (=.ai/scripts/agent-lock=) provides the locks. The passes reuse existing workflows (=inbox.org=, =triage-intake.org=, =clean-todo.org=, =task-audit.org=) under sentry's unattended contract. +This file is the engine. It owns the entry gates, the branch mechanics, the lock model, the per-cycle pass runner, the digest and approval queue, the skip semantics, and the stop-sentry shutdown. The =agent-lock= helper (=.ai/scripts/agent-lock=) provides the locks. The passes reuse existing workflows (=inbox.org=, =triage-intake.org=, =clean-todo.org=, =task-audit.org=) under sentry's unattended contract. * When to Use This Workflow @@ -58,7 +58,7 @@ Craig types the sentry trigger, so the first moves run with him at the terminal. Wait for an answer. Sentry can't start unattended from a dirty state; that's the point. -3. *Green-suite gate.* Run the project's full suite (=make test=, or the project's equivalent — detect it). Read the output. If anything is red, describe the failures and offer to investigate before arming. The loop starts only on a green baseline, because every unattended fire measures itself against "did I break this?" and a pre-existing red poisons that check. +3. *Green-suite gate.* Run the project's full suite (=make test=, or the project's equivalent — detect it). Read the output. If anything is red, describe the failures and offer to investigate before arming. The loop starts only on a green baseline, because every unattended cycle measures itself against "did I break this?" and a pre-existing red poisons that check. 4. *Prior sentry branch.* =git branch --list 'sentry/*'=. An unmerged =sentry/*= branch from a previous night means the morning review didn't happen. Surface it and offer to squash-merge or delete it now (Craig is present); don't stack a second sentry branch on the first. @@ -75,53 +75,53 @@ Craig types the sentry trigger, so the first moves run with him at the terminal. The host suffix (=uname -n=) stops a same-date collision between the two daily drivers. The working tree now sits on this branch overnight — the launch hands the repo to sentry until the morning merge. Reclaiming it mid-night means stopping sentry first (see Stop Sentry). Note the Emacs buffer-revert caveat to Craig if he has the repo open: files change on disk under him overnight, so buffers want reverting after the morning merge (see =emacs.md=). -7. *Arm the loop.* Start =/loop= at the interval (default hourly; Craig's "every <interval>" phrase overrides) with the per-fire body being one sentry fire (the Pass Runner below). Confirm the arming in one line: interval, branch name, project. +7. *Arm the loop.* Start =/loop= at the interval (default hourly; Craig's "every <interval>" phrase overrides) with the per-cycle body being one sentry cycle (the Pass Runner below). Confirm the arming in one line: interval, branch name, project. * The lock model Two locks, both served by =.ai/scripts/agent-lock= (names only; the helper owns the paths, which live on tmpfs under =$XDG_RUNTIME_DIR/agent-locks/=, host-local and cleared on reboot). -*Single-runner lock* (=sentry-<project>=, where =<project>= is the repo-root basename: =basename "$(git rev-parse --show-toplevel)"= — the same derivation =wrap-it-up.org='s guard uses, so the two agree on the lock name). Each fire acquires it at fire start and releases it at fire end, and refreshes it between passes (the heartbeat, so a live fire's lock never ages past one pass). If =/loop= fires again while a previous fire still holds it, the new fire's acquire fails and the fire skips with one digest line — no two fires run at once. The bounded wait is short (a few seconds); a live fire means defer, not queue. +*Single-runner lock* (=sentry-<project>=, where =<project>= is the repo-root basename: =basename "$(git rev-parse --show-toplevel)"= — the same derivation =wrap-it-up.org='s guard uses, so the two agree on the lock name). Each cycle acquires it at cycle start and releases it at cycle end, and refreshes it between passes (the heartbeat, so a live cycle's lock never ages past one pass). If =/loop= fires again while a previous cycle still holds it, the new cycle's acquire fails and the cycle skips with one digest line — no two cycles run at once. The bounded wait is short (a few seconds); a live cycle means defer, not queue. *Roam-write lock* (=roam-write=). A pass that edits a file under =~/org/roam= acquires it, runs =capture-guard --wait= (the human-capture layer stays underneath), edits the working tree, triggers =systemctl --user start roam-sync.service=, and releases. The lock spans only edit-plus-trigger. Sentry never runs =git= against =~/org/roam= — roam-sync stays the repo's only committer (the 2026-06-24 one-git-owner rule). Pass 1's =pull --ff-only= is the sole, read-only exception. -Every reclaim of a stale lock surfaces in the digest — the helper prints the reclaim note, and the fire records it. A reclaim during a genuinely slow pass is possible, so it's never silent. +Every reclaim of a stale lock surfaces in the digest — the helper prints the reclaim note, and the cycle records it. A reclaim during a genuinely slow pass is possible, so it's never silent. * The Pass Runner — one contract per pass -Each fire, after acquiring the single-runner lock and verifying branch state (below), walks the pass list in order. Every pass follows the same four-step contract: +Each cycle, after acquiring the single-runner lock and verifying branch state (below), walks the pass list in order. Every pass follows the same four-step contract: 1. *Probe* — a cheap existence check for the pass's target (named per pass below). Absent → the pass is one skip line in the digest and nothing more. This is what makes the pass list portable: passes self-activate where their target exists and stay silent elsewhere, with zero per-project configuration. 2. *Work* — run the pass under the unattended contract. Quick, solo, already-agreed mechanical actions execute. Anything destructive or requiring judgment does *not* execute — it appends to the morning-approval queue (what, why, the exact command or edit that fires on approval). A pass runs fully or not at all; there is no reduced-form pass. -3. *Session-context entry* — a pass that does or queues work appends its digest line to the =session-context.org= Session Log (path resolved via =.ai/scripts/session-context-path=) before its commit, so a crash between them still leaves the trail. Per-pass lines for an all-quiet fire (every pass probe-skipped or no-op) are not written one by one — the fire collapses to a single heartbeat at fire-end (below), so an idle fire doesn't spray one skip line per pass. +3. *Session-context entry* — a pass that does or queues work appends its digest line to the =session-context.org= Session Log (path resolved via =.ai/scripts/session-context-path=) before its commit, so a crash between them still leaves the trail. Per-pass lines for an all-quiet cycle (every pass probe-skipped or no-op) are not written one by one — the cycle collapses to a single heartbeat at cycle-end (below), so an idle cycle doesn't spray one skip line per pass. 4. *Commit* — if the pass wrote to disk, commit it: =chore(sentry): <pass> — <what changed>=. One commit per writing pass. A probe-skip or a no-op pass writes nothing and commits nothing. Between passes, refresh the single-runner lock (=agent-lock refresh sentry-<project>=) — the heartbeat. -** Branch-state verification (fire start, before the passes) +** Branch-state verification (cycle start, before the passes) -After acquiring the lock, confirm the fire is safe to run: +After acquiring the lock, confirm the cycle is safe to run: -- *On the right branch* — HEAD is =sentry/<today>-<host>=. If the loop was armed on a prior day and crossed midnight, the branch keeps the arming date; that's fine, morning teardown handles it. If HEAD is somehow *not* a sentry branch (an interrupted stop, a manual checkout), skip the whole fire with a digest line rather than committing onto main. -- *Clean of foreign changes* — =git diff --quiet HEAD= excluding the spine set (=session-context.org= / =session-context.d/=, resolved via =session-context-path=). Sentry's own spine writes must not trip this; a genuinely unexpected dirty tree (something outside the spine changed and wasn't committed by a prior pass) poisons the fire — skip it with a digest line, the next fire retries. +- *On the right branch* — HEAD is =sentry/<today>-<host>=. If the loop was armed on a prior day and crossed midnight, the branch keeps the arming date; that's fine, morning teardown handles it. If HEAD is somehow *not* a sentry branch (an interrupted stop, a manual checkout), skip the whole cycle with a digest line rather than committing onto main. +- *Clean of foreign changes* — =git diff --quiet HEAD= excluding the spine set (=session-context.org= / =session-context.d/=, resolved via =session-context-path=). Sentry's own spine writes must not trip this; a genuinely unexpected dirty tree (something outside the spine changed and wasn't committed by a prior pass) poisons the cycle — skip it with a digest line, the next cycle retries. * Unattended safety — skip, never degrade -With no one at the terminal, any unsafe state makes the affected scope skip with one digest line, and the next fire retries. Unsafe states and their scope: +With no one at the terminal, any unsafe state makes the affected scope skip with one digest line, and the next cycle retries. Unsafe states and their scope: -- *Unexpected dirty tree* (non-spine) → skip the whole fire. -- *Lost or un-acquirable single-runner lock* → skip the fire (another fire holds it, or the helper is missing). +- *Unexpected dirty tree* (non-spine) → skip the whole cycle. +- *Lost or un-acquirable single-runner lock* → skip the cycle (another cycle holds it, or the helper is missing). - *A pass's own precondition unmet* (its probe fails, or a dependency is dirty) → skip that pass only. -- *Red suite at fire-end* (see below) → the commits stay on the branch, flagged in the digest for morning review; the fire doesn't roll back. +- *Red suite at cycle-end* (see below) → the commits stay on the branch, flagged in the digest for morning review; the cycle doesn't roll back. -Skips are never silent and never partial. Inside a *working* fire, a pass line means the pass fully ran and a skip line names why it didn't. An *all-quiet* fire is not a silent skip either: its single =sentry at HH:MM: nothing= heartbeat is the explicit record that every pass found nothing, standing in for a wall of identical skip lines. The anti-silence rule targets a pass that hides work it should have surfaced; a quiet fire has surfaced that there was none. +Skips are never silent and never partial. Inside a *working* cycle, a pass line means the pass fully ran and a skip line names why it didn't. An *all-quiet* cycle is not a silent skip either: its single =sentry at HH:MM: nothing= heartbeat is the explicit record that every pass found nothing, standing in for a wall of identical skip lines. The anti-silence rule targets a pass that hides work it should have surfaced; a quiet cycle has surfaced that there was none. ** Multi-day stall notification -An unmerged prior =sentry/*= branch at fire start (the morning review never happened) skips the fire. After the *second consecutive* fire skipped for this reason, send one persistent desktop notification naming the project and branch: +An unmerged prior =sentry/*= branch at cycle start (the morning review never happened) skips the cycle. After the *second consecutive* cycle skipped for this reason, send one persistent desktop notification naming the project and branch: : sentry stalled: <branch> unmerged — merge or delete to resume @@ -135,11 +135,11 @@ In order. Each names its detection probe. A pass whose probe fails is one skip l 2. *Inbox zero* — run =inbox.org= roam mode under the no-approvals contract: quick+solo+agreed items execute, shared-asset and convention proposals park (prepared diff, =VERIFY= task, sender reply) in the approval queue. Edits to =~/org/roam/inbox.org= take the roam-write lock + =capture-guard=. Probe: the roam clone or a project =inbox/= exists. Tidying the shared roam inbox is allowed from *any* project session, work included — it's housekeeping on a shared resource, not a durable KB-node write, so the work-denylist doesn't gate it (=knowledge-base.md=). Never park it as a cross-project boundary crossing. -3. *Triage intake — mail and messenger sources excluded.* Run =triage-intake.org=, loading only its non-mail, non-messenger source plugins (calendar, PR/ticketing). The mail and messenger plugins — cmail, any Gmail variant, Telegram, Signal, chat DMs — are never loaded by a sentry fire: Craig ruled 2026-07-21 that sentry doesn't check email or messengers. A manual "triage intake" still scans everything. Probe: the project has at least one *active* triage source that survives that exclusion — a project-specific plugin (=.ai/project-workflows/triage-intake.*.org=), or a non-empty =:TRIAGE_SOURCES:= declaration naming general plugins that exist. Mere presence of the template-synced general plugins does *not* activate the pass; a project that declares no sources, or whose only declared sources are mail or messengers, probe-skips (see =docs/specs/2026-07-20-triage-source-activation-spec.org=). Destructive actions (deleting, archiving, sending) queue; they never fire unattended. +3. *Triage intake — mail and messenger sources excluded.* Run =triage-intake.org=, loading only its non-mail, non-messenger source plugins (calendar, PR/ticketing). The mail and messenger plugins — cmail, any Gmail variant, Telegram, Signal, chat DMs — are never loaded by a sentry cycle: Craig ruled 2026-07-21 that sentry doesn't check email or messengers. A manual "triage intake" still scans everything. Probe: the project has at least one *active* triage source that survives that exclusion — a project-specific plugin (=.ai/project-workflows/triage-intake.*.org=), or a non-empty =:TRIAGE_SOURCES:= declaration naming general plugins that exist. Mere presence of the template-synced general plugins does *not* activate the pass; a project that declares no sources, or whose only declared sources are mail or messengers, probe-skips (see =docs/specs/2026-07-20-triage-source-activation-spec.org=). Destructive actions (deleting, archiving, sending) queue; they never cycle unattended. -4. *Todo cleanup* — the =clean-todo.org= mechanics (hygiene pass + =--archive-done= + =--convert-subtasks=). Probe: a root =todo.org=. Note that =--archive-done= is not purely an org-file pass on its first run in a project: it creates =archive/task-archive.org= and appends a =.gitignore= entry, so it produces a real tracked-file commit and correctly trips the fire-end conditional suite. (archangel, first live run 2026-07-21.) +4. *Todo cleanup* — the =clean-todo.org= mechanics (hygiene pass + =--archive-done= + =--convert-subtasks=). Probe: a root =todo.org=. Note that =--archive-done= is not purely an org-file pass on its first run in a project: it creates =archive/task-archive.org= and appends a =.gitignore= entry, so it produces a real tracked-file commit and correctly trips the cycle-end conditional suite. (archangel, first live run 2026-07-21.) -5. *Task audit* — the *mechanical subset* of =task-audit.org= hourly (staleness counts, structural checks, cookie recomputation); the judgment half (priority regrades, consolidations, merge candidates) runs *once per night* and queues its findings rather than repeating them every fire. Probe: a root =todo.org=. A full audit every hour is too heavy and re-surfaces the same judgment calls all night. (takuzu, first live run 2026-07-21.) Factual staleness fixes that are unambiguous still execute. +5. *Task audit* — the *mechanical subset* of =task-audit.org= hourly (staleness counts, structural checks, cookie recomputation); the judgment half (priority regrades, consolidations, merge candidates) runs *once per night* and queues its findings rather than repeating them every cycle. Probe: a root =todo.org=. A full audit every hour is too heavy and re-surfaces the same judgment calls all night. (takuzu, first live run 2026-07-21.) Factual staleness fixes that are unambiguous still execute. 6. *Working-files hygiene* — flag =working/<slug>/= directories whose backing task is closed (a filing candidate per =working-files.md=). Probe: a =working/= directory exists. The filing itself queues (it's a judgment move). @@ -151,25 +151,25 @@ In order. Each names its detection probe. A pass whose probe fails is one skip l 10. *Prep + symlink freshness* — stale daily-prep docs, broken symlinks. Probe: the prep dir / symlinks exist (work and home only, in practice). -11. *Bug and refactor finding* — hunt for real bugs and worthwhile refactoring opportunities in the project's codebase: static analysis (=shellcheck= for shell, the project's own linters for its languages), config sanity checks, plus one targeted code-reading area per fire. Rotate the area across fires and name it in the digest, so coverage accumulates over a night instead of re-reading the same corner. Randomized property sweeps (generate-and-verify against an engine's own invariants) are good quiet-fire work here, reaching past a frozen test corpus. Expect the pass to go honestly quiet after the first few fires find the standing defects; a quiet hunt is a result, not a failure. (takuzu, first live run 2026-07-21: three real fixes in the first four fires, then quiet.) This pass does *not* run the test suite — the entry baseline already ran it, and re-running it hourly is anti-pattern 5; read the entry result instead. Probe: the project carries a codebase — source under version control beyond its org and tooling files. File each verified bug as a graded task in =todo.org= per the severity × frequency matrix (=todo-format.md=), and each refactoring opportunity as a =:refactor:= task, deduped against existing tasks; an unverifiable suspicion is a digest line, not a task. *Find, never fix in this pass* — the finding files a task and stops. A fix happens only in the opt-in implementation pass below, and only after the finding is a filed task that pass then re-verifies from scratch (see the premise rule there). A freshly-found "bug" can be a misread — one was filed and retracted two fires apart on 2026-07-23 — so the file-then-verify-then-fix pipeline is deliberate: the task is the checkpoint, not a same-breath fix. (Added at Craig's order 2026-07-21, first dogfooded in dotfiles; refactor-finding added 2026-07-24.) +11. *Bug and refactor finding* — hunt for real bugs and worthwhile refactoring opportunities in the project's codebase: static analysis (=shellcheck= for shell, the project's own linters for its languages), config sanity checks, plus one targeted code-reading area per cycle. Rotate the area across cycles and name it in the digest, so coverage accumulates over a night instead of re-reading the same corner. Randomized property sweeps (generate-and-verify against an engine's own invariants) are good quiet-cycle work here, reaching past a frozen test corpus. Expect the pass to go honestly quiet after the first few cycles find the standing defects; a quiet hunt is a result, not a failure. (takuzu, first live run 2026-07-21: three real fixes in the first four cycles, then quiet.) This pass does *not* run the test suite — the entry baseline already ran it, and re-running it hourly is anti-pattern 5; read the entry result instead. Probe: the project carries a codebase — source under version control beyond its org and tooling files. File each verified bug as a graded task in =todo.org= per the severity × frequency matrix (=todo-format.md=), and each refactoring opportunity as a =:refactor:= task, deduped against existing tasks; an unverifiable suspicion is a digest line, not a task. *Find, never fix in this pass* — the finding files a task and stops. A fix happens only in the opt-in implementation pass below, and only after the finding is a filed task that pass then re-verifies from scratch (see the premise rule there). A freshly-found "bug" can be a misread — one was filed and retracted two cycles apart on 2026-07-23 — so the file-then-verify-then-fix pipeline is deliberate: the task is the checkpoint, not a same-breath fix. (Added at Craig's order 2026-07-21, first dogfooded in dotfiles; refactor-finding added 2026-07-24.) -12. *Solo-task implementation (opt-in — =:SENTRY_MAY_IMPLEMENT:=)* — work the backlog's solo, decision-free tasks on the branch. Probe: =.ai/notes.org= Workflow State carries =:SENTRY_MAY_IMPLEMENT: yes= *and* the project holds =:COMMIT_AUTONOMY:= (the implement pass commits). Absent the marker, skip — this pass is off by default, because it turns the morning from a two-minute merge into a code review, and that's the project owner's call. When on: invoke =work-the-backlog.org= under its unattended-loop contract (no pre-flight Q&A — there's no Craig overnight), eligibility =TODO= + =:solo:=, with the defer checklist deciding act-vs-file. The overnight-only tightening: only the *ready* bucket implements (clears every checklist item with zero open decisions); a task needing even one quick decision defers to a =VERIFY= rather than guessing, exactly as the loop caller already does. Commit each logical change to the sentry branch; *never push* — the morning review and merge is the gate, same as every other pass. The full quality bar holds (TDD, suite green before each commit, =/review-code=, =/voice=), and =/review-code= here runs the *premise check first*: reproduce the bug or confirm the problem is real before judging the diff. The review is the fact-checker that a filed claim never got, and it is what makes fixing-on-a-branch safe (Craig, 2026-07-24). A task that fails its premise check is not implemented — the finding was wrong, and that outcome is a digest line, not a commit. (Added at Craig's direction 2026-07-24: overnight implement-on-branch, gated and never-pushed.) +12. *Solo-task implementation (opt-in — =:SENTRY_MAY_IMPLEMENT:=)* — work the backlog's solo, decision-free tasks on the branch. Probe: =.ai/notes.org= Workflow State carries =:SENTRY_MAY_IMPLEMENT: yes= *and* the project holds =:COMMIT_AUTONOMY:= (the implement pass commits). Absent the marker, skip — this pass is off by default, because it turns the morning from a two-minute merge into a code review, and that's the project owner's call. When on: invoke =work-the-backlog.org= under its unattended-loop contract (no pre-flight Q&A — there's no Craig overnight), eligibility =TODO= + =:solo:=, with the defer checklist deciding act-vs-file. The overnight-only tightening: only the *ready* bucket implements (clears every checklist item with zero open decisions); a task needing even one quick decision defers to a =VERIFY= rather than guessing, exactly as the loop caller already does. Commit each logical change to the sentry branch; *never push* — the morning review and merge is the gate, same as every other pass. The full quality bar holds (TDD, suite green before each commit, the isolated adversarial review per =publish= Step 1 with its re-review loop, =/voice=), and the review here runs the *premise check first*: reproduce the bug or confirm the problem is real before judging the diff. The review is the fact-checker that a filed claim never got, and it is what makes fixing-on-a-branch safe (Craig, 2026-07-24). A task that fails its premise check is not implemented — the finding was wrong, and that outcome is a digest line, not a commit. A task whose review never reaches approval — three rounds, a recurring finding, or a =Needs Discussion= verdict — is the same shape: no commit, and a digest line naming the standing findings, so the morning review sees what the reviewer would not pass rather than finding the task silently absent. (Added at Craig's direction 2026-07-24: overnight implement-on-branch, gated and never-pushed.) (KB lesson promotion — the pass the original proposal listed eleventh — is deferred to vNext. An unattended judgment pass writing to the shared knowledge base waits until sentry has quiet weeks behind it and a designed detection heuristic. See the filed lesson-detection-heuristic task.) -* Fire-end — conditional suite, then the digest commit +* Cycle-end — conditional suite, then the digest commit After the passes: -1. *Conditional suite run.* If any pass this fire modified files *outside* the org/spine set (a code-touching pass, rare but possible via fixtures), run the full suite once. A green run confirms the fire's commits are safe; a red run flags the digest for morning review — the commits stay on the branch (nothing is pushed, so the morning gate catches it). No per-pass suite runs: the entry run is the green baseline, and hourly per-commit runs would turn a seconds-long fire into minutes all night. Fires that only touched org/spine files skip this. +1. *Conditional suite run.* If any pass this cycle modified files *outside* the org/spine set (a code-touching pass, rare but possible via fixtures), run the full suite once. A green run confirms the cycle's commits are safe; a red run flags the digest for morning review — the commits stay on the branch (nothing is pushed, so the morning gate catches it). No per-pass suite runs: the entry run is the green baseline, and hourly per-commit runs would turn a seconds-long cycle into minutes all night. Cycles that only touched org/spine files skip this. -2. *Heartbeat or digest, then commit.* Decide quiet vs working. A *quiet* fire — every pass probe-skipped or no-op, nothing added to the approval queue — writes a single heartbeat line to the Session Log, =sentry at HH:MM: nothing= (HH:MM local, from =date=), and no per-pass digest block. A *working* fire — any pass ran, wrote, or queued — writes its full per-pass digest block. Then commit any accumulated spine writes in one sweep: =chore(sentry): digest — <date> <time> fire= for a working fire, =chore(sentry): heartbeat — <date> <time>= for a quiet one, so even a quiet fire leaves a clean tree for the next branch-state check (where the spine is untracked, the mirror-only case, there is nothing to commit and the heartbeat line stays in the working-tree anchor). This is the silent-until-signal policy (see =docs/specs/2026-07-20-silent-until-signal-monitors-spec.org=): an all-quiet night collapses from a wall of no-op digests to a list of one-line heartbeats, while a fire that actually did or queued something still writes the full record. +2. *Heartbeat or digest, then commit.* Decide quiet vs working. A *quiet* cycle — every pass probe-skipped or no-op, nothing added to the approval queue — writes a single heartbeat line to the Session Log, =sentry at HH:MM: nothing= (HH:MM local, from =date=), and no per-pass digest block. A *working* cycle — any pass ran, wrote, or queued — writes its full per-pass digest block. Then commit any accumulated spine writes in one sweep: =chore(sentry): digest — <date> <time> cycle= for a working cycle, =chore(sentry): heartbeat — <date> <time>= for a quiet one, so even a quiet cycle leaves a clean tree for the next branch-state check (where the spine is untracked, the mirror-only case, there is nothing to commit and the heartbeat line stays in the working-tree anchor). This is the silent-until-signal policy (see =docs/specs/2026-07-20-silent-until-signal-monitors-spec.org=): an all-quiet night collapses from a wall of no-op digests to a list of one-line heartbeats, while a cycle that actually did or queued something still writes the full record. 3. *Release the single-runner lock.* * The digest and the approval queue -*Digest.* A *working* fire appends its block to the =session-context.org= Session Log (the spine the fire already writes), so it survives a crash, rides the session archive, and is on screen in the running session. One block per working fire: the timestamp, then one line per pass (ran + what, or skipped + why), plus any lock reclaim notes. A *quiet* fire (nothing done or queued) writes no block — just the one heartbeat line =sentry at HH:MM: nothing= (the silent-until-signal policy). The per-pass block is a working-fire artifact; it still carries one line per pass so a real skip inside a working fire is never hidden. +*Digest.* A *working* cycle appends its block to the =session-context.org= Session Log (the spine the cycle already writes), so it survives a crash, rides the session archive, and is on screen in the running session. One block per working cycle: the timestamp, then one line per pass (ran + what, or skipped + why), plus any lock reclaim notes. A *quiet* cycle (nothing done or queued) writes no block — just the one heartbeat line =sentry at HH:MM: nothing= (the silent-until-signal policy). The per-pass block is a working-cycle artifact; it still carries one line per pass so a real skip inside a working cycle is never hidden. *Approval queue.* Destructive and judgment actions accumulate under one heading in the same file — =* Sentry approval queue (<date>)= — newest last. Each item carries three things: *what* (the action), *why* (what triggered it), and the *exact command or edit* that fires on approval. The morning review is Craig reading this heading top to bottom and running or discarding each item. @@ -186,13 +186,13 @@ Sentry never merges its own branch. In the morning Craig: A bad night is discarded by deleting one branch — nothing reached main, nothing was pushed. -In a project that gitignores =.ai/=, the whole spine is untracked, so quiet fires produce no commits at all and =git log main..sentry/<date>-<host>= understates the night's activity. There the anchor's heartbeat list is the only record of what fired. Read the anchor, not just the log. (archangel, first live run 2026-07-21.) +In a project that gitignores =.ai/=, the whole spine is untracked, so quiet cycles produce no commits at all and =git log main..sentry/<date>-<host>= understates the night's activity. There the anchor's heartbeat list is the only record of what fired. Read the anchor, not just the log. (archangel, first live run 2026-07-21.) * Stop Sentry Trigger: "stop sentry" (and synonyms above). Sentry owns its own shutdown: -1. *Cancel the loop* — stop the =/loop= (=ScheduleWakeup= stop / the loop's stop path). No further fires. +1. *Cancel the loop* — stop the =/loop= (=ScheduleWakeup= stop / the loop's stop path). No further cycles. 2. *Release the single-runner lock* if this context holds it. 3. *Branch disposition* — offer, inline-numbered: 1. Squash-merge the day's branch into main now (walk the morning teardown steps 3-5 interactively) @@ -208,14 +208,14 @@ Stopping sentry is the only way to reclaim the working tree mid-night. The entry * Common Mistakes 1. *Running without the =:COMMIT_AUTONOMY:= grant* — sentry commits unattended; the marker is the entry ticket, and its absence is a hard stop, not a degrade. -2. *Starting from a dirty or red tree* — the entry gates exist because an unattended fire can't tell Craig's in-progress work from a regression. Answer the gate; don't bypass it. -3. *Committing onto main* — every writing pass commits to the daily =sentry/*= branch. A fire that finds HEAD off the sentry branch skips rather than commits. +2. *Starting from a dirty or red tree* — the entry gates exist because an unattended cycle can't tell Craig's in-progress work from a regression. Answer the gate; don't bypass it. +3. *Committing onto main* — every writing pass commits to the daily =sentry/*= branch. A cycle that finds HEAD off the sentry branch skips rather than commits. 4. *Running a =git= write against =~/org/roam=* — roam-sync is the only committer. Sentry edits the tree under the roam-write lock and triggers the sync; it never commits or pushes roam. -5. *A per-pass suite run* — the suite runs at entry (baseline) and conditionally at fire-end (only when a pass touched non-org files). Hourly per-commit runs all night is the anti-pattern the suite policy exists to prevent. +5. *A per-pass suite run* — the suite runs at entry (baseline) and conditionally at cycle-end (only when a pass touched non-org files). Hourly per-commit runs all night is the anti-pattern the suite policy exists to prevent. 6. *Executing a judgment or destructive action unattended* — those queue for the morning with their exact command. The pass did its detection; Craig makes the call. The one sanctioned exception is pass 12's solo-task implementation, and only because it inherits work-the-backlog's full defer checklist (data-loss and irreversible actions defer, never execute) plus a premise-verifying review, and it commits to the branch rather than acting on anything live. -7. *A silent skip* — inside a working fire, every skip writes a digest line naming why; a missing pass with no line reads as "ran clean" when it didn't. The one exception is not a violation: an all-quiet fire collapses to a single =sentry at HH:MM: nothing= heartbeat instead of one skip line per pass — the heartbeat is the explicit "nothing to do" record, per the silent-until-signal policy. +7. *A silent skip* — inside a working cycle, every skip writes a digest line naming why; a missing pass with no line reads as "ran clean" when it didn't. The one exception is not a violation: an all-quiet cycle collapses to a single =sentry at HH:MM: nothing= heartbeat instead of one skip line per pass — the heartbeat is the explicit "nothing to do" record, per the silent-until-signal policy. 8. *Degrading a pass to a reduced form* — a pass runs fully or skips. No half-passes. -9. *Letting an unmerged branch stall silently* — after two consecutive unmerged-branch skips, the persistent desktop notify fires. Don't suppress it. +9. *Letting an unmerged branch stall silently* — after two consecutive unmerged-branch skips, the persistent desktop notify cycles. Don't suppress it. 10. *Merging sentry's branch automatically* — the morning teardown is Craig's. Sentry creates and commits; it never merges or deletes its own branch. * Living Document diff --git a/.ai/workflows/startup.org b/.ai/workflows/startup.org index 2262eea..bc89256 100644 --- a/.ai/workflows/startup.org +++ b/.ai/workflows/startup.org @@ -137,39 +137,24 @@ These calls have no dependencies on each other. Issue them all together in one m #+end_src 3. *Sync =.ai/= from templates — but only when the synced source paths in rulesets are clean.* Guard the three rsyncs behind a check that =claude-templates/.ai/{protocols.org,workflows/,scripts/}= have no uncommitted changes. Otherwise Phase A copies in-flight rulesets WIP (tracked edits or new untracked files) into this project's =.ai/workflows/= and =.ai/scripts/=, where it shows up as drift the user didn't author. Skipping once is cheap — the next session with rulesets clean catches up. The check is scoped to the synced paths, so unrelated rulesets dirt (a stray =session-context.org=, scratch files) doesn't needlessly block the sync. A second guard skips the same rsyncs when the *project* branch is behind its upstream (=git rev-list --left-right --count @{u}...HEAD= with =behind > 0=): syncing templates onto a stale committed =.ai/= baseline measures the diff against old content, so it comes out huge and conflicts when the branch later reconciles to upstream, whose history already carries the newer templates. It composes with the rulesets-clean guard — a stable rulesets source and a current project branch are both required before the sync runs. - #+begin_src bash - rs="$HOME/code/rulesets" - synced_dirty=$(cd "$rs" && git status --porcelain -- \ - claude-templates/.ai/protocols.org \ - claude-templates/.ai/workflows/ \ - claude-templates/.ai/scripts/ 2>/dev/null) - # Skip the sync when the project branch hasn't reached its upstream. Syncing - # templates onto a behind baseline measures the diff against stale committed - # .ai/, producing confusing drift that conflicts when the branch reconciles — - # the newer .ai/ is already in upstream. behind==0 (up-to-date or ahead-only) - # means HEAD contains all of upstream, so the baseline is current. No upstream - # (new/unpushed branch) → rev-list fails → proj_behind stays 0, sync runs. - proj_behind=0 - if [ -d .git ]; then - counts=$(git rev-list --left-right --count '@{u}...HEAD' 2>/dev/null) \ - && [ "$(printf '%s' "$counts" | cut -f1)" -gt 0 ] 2>/dev/null \ - && proj_behind=1 - fi + The logic lives in =.ai/scripts/sync-templates=, not inline here. It was extracted 2026-07-31 after an uncommitted edit in rulesets silently blocked all three rsyncs for a full day — five workflow files went stale in one downstream project alone, with nothing anywhere reporting it. A mechanism that distributes correctness fixes to every project needs tests, and inline bash in an org file cannot have them. The behavior is unchanged by the extraction (verified differentially, output and resulting tree both byte-identical); the guards it applies are described below. - if [ -n "$synced_dirty" ]; then - echo "rulesets has uncommitted changes under the synced template paths — skipping .ai/ sync this session (catches up when rulesets is clean):" - echo "$synced_dirty" | sed 's/^/ /' - elif [ "$proj_behind" -eq 1 ]; then - echo "project branch is behind upstream — skipping .ai/ sync this session (templates never land on a stale baseline; the sync runs once the branch is current)" + #+begin_src bash + if [ -x .ai/scripts/sync-templates ]; then + .ai/scripts/sync-templates else - rsync -a "$rs/claude-templates/.ai/protocols.org" .ai/protocols.org - rsync -a --delete "$rs/claude-templates/.ai/workflows/" .ai/workflows/ - rsync -a --delete --exclude='__pycache__' --exclude='.pytest_cache' --exclude='*.pyc' \ - "$rs/claude-templates/.ai/scripts/" .ai/scripts/ - echo ".ai/ synced from templates" + echo "sync-templates not present — .ai/ sync SKIPPED and cannot self-heal; recover with: bash ~/code/rulesets/scripts/audit.sh --apply --force" fi #+end_src + The fallback should never fire in the ordinary rollout. A project still on the pre-extraction startup.org runs the old inline block this session, which delivers both the script and this file together, and the next session finds the script in place. It covers only the split case — the =workflows/= rsync landing while the =scripts/= one didn't — where a project would otherwise hold this file with no script to call. + + *That state does not self-heal, which is why the message names a command.* The fallback runs /instead of/ the sync, so there is no later sync to deliver the missing script: the project would announce one line per session forever while its templates froze. Recovery is out-of-band, via =scripts/audit.sh --apply --force= in rulesets, which rsyncs =scripts/= directly. =--force= is there because audit skips a tracked project holding uncommitted =.ai/= changes, which a project wedged across several sessions is likely to be. + + One caveat on that recovery, worth knowing before running it: audit's =scripts/= rsync carries none of the =__pycache__= / =.pytest_cache= / =*.pyc= excludes this sync does, so it can deposit python cache artifacts that then need removing by hand. Tracked separately; it is a pre-existing gap in audit rather than something this path introduced. + + Announcing the skip loudly with its remedy is the point; a silent skip is the exact failure this extraction exists to stop. + 4. =\ls -t .ai/sessions/ 2>/dev/null | head -5= — list 5 most recent session files. The backslash bypasses any =ls= alias in the user's profile. Without it, bare =ls -t= silently returns no output under =exa= (a common =ls= replacement) — which makes a sessions directory full of files look empty, and the agent then skips Phase B step 2. 5. =\ls -la inbox/ 2>/dev/null= — inventory the inbox. Same reason for the backslash escape, applied uniformly across the Phase A =ls= calls. 6. Read =.ai/notes.org= — Project-Specific Context, Active Reminders, Pending Decisions sections (skip About This File). @@ -213,7 +198,7 @@ These calls have no dependencies on each other. Issue them all together in one m Fleet descriptions ("the fleet is ratio and velox") and runtime derivations ("run =uname -n= to find the hostname") don't match — only current-identity assertions do. Fixture-verified under bash and zsh. -Notes on the rsync commands: +Notes on what =sync-templates= does (the rsync behavior it carries): - Trailing slashes on both source and destination matter — they tell rsync to sync /contents/ rather than nest a directory inside. - =--delete= on the directory syncs lets retired template files actually disappear from each project on next startup. - protocols.org is a single file, no =--delete= needed. diff --git a/.ai/workflows/triage-intake.telegram.org b/.ai/workflows/triage-intake.telegram.org index 5039a8b..1319da5 100644 --- a/.ai/workflows/triage-intake.telegram.org +++ b/.ai/workflows/triage-intake.telegram.org @@ -30,12 +30,27 @@ Telega does not autostart with the Emacs daemon. "Down" is its normal state unless Craig has Telegram open in Emacs. The scan therefore runs the full lifecycle every time, never skips because the server is down: +⚠ *DOWN / not-loaded is the TRIGGER to launch, never a reason to skip or fail.* +This is the exact mistake two projects (work + home, 2026-07-24) made: they +probed telega, saw =(telega-server-live-p)= nil or telega not =featurep=, and +reported =SCAN FAILED: telegram — not loaded= or a silent SKIP — a *blind* +sweep — instead of running Step 1 to start it. A down or unloaded telega is the +normal entry state; =(telega t)= both LOADS the package and STARTS the docker +server (work confirmed: down → =(telega t)= → Ready, 18 chats). So the plugin +MUST run Step 1's launch whenever telega is down/unloaded, wait for Ready, then +scan. =SCAN FAILED= is reserved for a launch that was actually ATTEMPTED and did +not reach Ready (image missing, server crash on start, daemon unreachable) — +never for the pre-launch down state itself. The =:ENABLED:= guard above tests +whether telega is INSTALLED (=fboundp=), not whether the server is up; a down +server never disables the source. + 1. Record prior state: TELEGA_WAS_RUNNING via (telega-server-live-p). 2. Launch (only if not running): emacsclient -e "(progn (setq telega-use-docker t) (telega t) 'started)" - The setq is mandatory defense: tdlib segfaults outside docker mode - (2026-06-09), and Craig's daemon currently has telega-use-docker nil. - Wait ~2s for Ready, then (telega--loadChats 'main) until telega--chats + The setq is mandatory defense: tdlib crashed in native mode when this was + set up (2026-06-09) — a separate matter from the SEGFAULT gotcha, which is + about the loadChats argument — and Craig's daemon defaults to nil. + Wait ~2s for Ready, then (telega--loadChats '(:@type "chatListMain")) until telega--chats is populated. 3. Check messages: the maphash unread scan in ** Scan Step 2 (filters the messageContactRegistered join-notice noise). @@ -48,10 +63,13 @@ lifecycle every time, never skips because the server is down: Verify: telega-server-live-p → nil, no zevlg/telega-server container in docker ps. If Craig had it running, leave it untouched. -If any lifecycle step fails (docker image missing, server crash, daemon -unreachable), the sweep reports it as SCAN FAILED at the top of the summary -per the engine's failure rule — never as a silent skip. Craig gets real -traffic here. +If any lifecycle step fails *after the launch was attempted* (docker image +missing, server crash on start, daemon unreachable, Ready never reached), the +sweep reports it as SCAN FAILED at the top of the summary per the engine's +failure rule — never as a silent skip. This does NOT cover the ordinary +pre-launch down state: a down server means "run Step 1," not "SCAN FAILED." +Craig gets real traffic here, so a blind sweep that skipped the launch is worse +than a clean failure — it hides real unread messages behind a false all-clear. ** Scan @@ -85,22 +103,58 @@ TELEGA_WAS_RUNNING=$(emacsclient -e "(and (fboundp 'telega-server-live-p) (teleg *** Step 1 — start (docker mode) if not already running, wait for Ready #+begin_src bash -# `(telega t)` starts without popping the root buffer. Docker mode (the stable -# path — see the SEGFAULT gotcha) reconnects the persisted ~/.telega session in -# ~2s. Then load the main chat list so telega--chats populates. +# `(telega t)` starts without popping the root buffer. Docker mode reconnects the +# persisted ~/.telega session in ~2s. Then load the main chat list so +# telega--chats populates. +# +# The `(setq telega-use-docker t)` is mandatory and must come BEFORE `(telega t)`: +# tdlib crashed in native mode when this was first set up (2026-06-09), and the +# daemon's default is nil unless something (e.g. an Emacs-config :custom) has +# already forced it. It was missing here while the Quick Reference required it — +# a session that started telega without it on a native-mode daemon would take the +# untested path. Match the Quick Reference exactly. +# +# Note this is a SEPARATE concern from the SEGFAULT gotcha below: that gotcha is +# about the `loadChats` argument, and the deaths it explains happened in docker +# mode. Docker mode is not a defense against it, and it is not evidence for +# docker mode. Keep both. emacsclient -e "(progn + (setq telega-use-docker t) (unless (and (fboundp 'telega-server-live-p) (telega-server-live-p)) (telega t)) 'started)" # Poll until Ready with chats synced, or a crash/timeout. Background this with an # until-loop so the wait doesn't block; exit on Ready-with-chats OR an abnormal # server exit. Then force a chat-list load if the hash is thin: -emacsclient -e "(progn (ignore-errors (telega--loadChats 'main)) (ignore-errors (telega--loadChats 'main)) 'loaded)" +# NOTE: the chat-list argument must be a TL object, not the symbol 'main. +# `telega--loadChats' puts it straight into the request as :chat_list, and a +# bare symbol kills the server outright (see the SEGFAULT gotcha below). +# +# The liveness check on the tail is the load's only failure signal. `ignore-errors' +# catches nothing here, because a bad argument kills the server process rather than +# signalling in elisp, so without this the call returns 'loaded either way. +# The `fboundp' guard matches Step 0: if the launch failed outright telega is not +# loaded, and that should read as 'server-died like any other failure rather than +# signalling void-function. +emacsclient -e "(progn (ignore-errors (telega--loadChats '(:@type \"chatListMain\"))) (ignore-errors (telega--loadChats '(:@type \"chatListMain\"))) (if (and (fboundp 'telega-server-live-p) (telega-server-live-p)) 'loaded 'server-died))" #+end_src On a persisted session telega reaches status "Ready" within ~2s; the chat list loads over a few more. If =(hash-table-count telega--chats)= is 0 or thin, re-issue =telega--loadChats= and poll until it stabilizes. +⚠ *=server-died= is SCAN FAILED, never a quiet account.* A server that dies +during the load leaves a thin =telega--chats= hash, and a thin hash reads exactly +like an account with little unread. That is the same false all-clear the +down/not-loaded rule exists to prevent, arriving one step later in the lifecycle. +It also fits the SCAN FAILED definition above: the launch was attempted and did +not hold. So on =server-died=, report SCAN FAILED rather than scanning, and never +report a low unread count from that run. + +This is the independent evidence the SEGFAULT gotcha asks for when it says to +treat a short chat list as a real short list. Without the check there is no way +to tell the two apart, which is how the =loadChats= crash stayed invisible +through two investigations. + *** Step 2 — read unread, classified by last-message type The single most important filter: =messageContactRegistered=. Telegram counts a @@ -157,24 +211,61 @@ stays non-nil). =telega-server-kill= is what actually stops the server. Call left in =docker ps=. Skipping this whole branch when =TELEGA_WAS_RUNNING= is t is the point of Step 0: never tear down a session Craig is actively using. -⚠ *SEGFAULT GOTCHA — crashes are spontaneous; treat server death as routine.* -The dockerized =telega-server= (=zevlg/telega-server:latest=, image built -2026-06-04, tdlib 1.8.64) SIGSEGVs (exit 139) *on its own*, minutes-to-hours -into a session — 11 host coredumps between 2026-06-09 and 2026-06-11, several at -times when no triage verb was running. The 2026-06-11 investigation reproduced -the crash-free verbs and the spontaneous deaths side by side: coredump -backtraces show a corrupted stack (memory corruption in the musl build), and -no newer image exists upstream. Earlier theories — "native mode is the trigger", -"toggle-read is the trigger" — were timing coincidences; the verbs are sound. +⚠ *SEGFAULT GOTCHA — this was our bug, not tdlib's. Root-caused 2026-07-28.* +=telega-server= dies with =Unexpected char 'm' in plist value= followed by +=Assertion failed: false (telega-dat.c: tdat_plist_value: 500)=. The cause was +this workflow: Step 1 called =(telega--loadChats 'main)=. + +The chain. =telega--loadChats= is a raw TL wrapper — it drops its argument into +the request as =:chat_list= with no conversion. =telega-server--send= then +=prin1='s the whole plist, and =telega--tl-pack= passes atoms through untouched, +so the symbol goes out on the wire bare as =main=. The C parser +(=server/telega-dat.c=, =tdat_plist_value=) accepts only =(=, =[=, ="=, =-=, a +digit, =t=, =:=, or =n= to start a value. It hits =m=, prints that line, and +calls =assert(false)=, which aborts the process. The =m= in the error is +literally the first character of =main=. + +The symbol shorthand is real but belongs to a different layer: +=telega-filter.el= and =telega-folders.el= convert =(eq cl-fspec 'main)= into +='(:@type "chatListMain")=. The raw TL layer never does. telega's own callers +always pass the object (=telega.el:290=, =telega-tdlib-events.el:516=). + +Proved by experiment, not inference (2026-07-28): from a live Ready server, +=(telega--loadChats 'main)= killed it within seconds and added one coredump, +with that exact assertion; a restart plus =(telega--loadChats '(:@type +"chatListMain"))= survived three consecutive calls with no new coredump and no +assertion. + +*The previous entry here was wrong and cost real time.* It recorded the deaths +as spontaneous musl memory corruption and declared "the verbs are sound", which +sent later investigations at the docker image and tdlib versions instead of at +this file. The corrupted stack in the backtraces is what an =assert= abort looks +like, not independent evidence of a memory bug. If crashes are ever seen again +with *no* triage verb running, that is a genuinely separate cause and needs its +own investigation — do not reuse the old spontaneous-crash story to explain it. + +*This crash kills a scan; it does not silently shorten one.* An earlier draft of +this section claimed the reported "19 chats of ~50" was truncation caused by the +bad call. That was wrong, and work disproved it at the wire level on 2026-07-28: +with the corrected call their count is 19 before the first load and 19 after five +(four on =chatListMain=, one on =chatListArchive=). Nineteen is the real size of +that account. The same reading here — 19 stable across three corrected loads — +was already sitting in the evidence and should have retired the claim before it +was written down. Treat a short chat list as a real short list unless something +independently shows the server died mid-sync. + +=ignore-errors= around the call never helped — the failure is the server process +dying, not an elisp signal, so there is nothing for it to catch. That is why the +death is easy to miss from inside elisp, and why a caller should check +=(process-live-p (telega-server--proc))= after a load rather than trusting a +returned value. Operationally: docker mode stays mandatory (=telega-use-docker= = t; the setq before =(telega t)= is still the right defense), and *every action batch checks the server first* — =(process-live-p (telega-server--proc))= — restarting via -=(telega t)= when dead and re-checking Ready before firing verbs. A mid-sweep -death is recoverable, not an abort: restart, confirm Ready, resume. Durable-fix -candidates if the crashing gets worse: pin a pre-2026-06 image digest, build -=telega-server= natively against tdlib, or report upstream to zevlg with the -coredumps (=coredumpctl list /usr/bin/telega-server=). +=(telega t)= when dead and re-checking Ready before firing verbs. Any argument +handed to a =telega--*= TL wrapper must be a TL object or a plain +string/number/list, never a bare symbol. Defense in depth: even if the server does die, the scan still works because it reads the cached =telega--chats= hash, not a live query. A dead server is diff --git a/.ai/workflows/work-the-backlog.org b/.ai/workflows/work-the-backlog.org index a0b24a8..ea3f402 100644 --- a/.ai/workflows/work-the-backlog.org +++ b/.ai/workflows/work-the-backlog.org @@ -54,7 +54,7 @@ For the task set, in order, until the run cap is hit: 1. *Eligibility gate* (below). Ineligible → record =skipped-ineligible=, next task. 2. *Scope read* of the relevant code. Cheap; just enough to run the defer checklist. 3. *Defer checklist* (below). Any hit → defer: file the =VERIFY= naming the gap and record =deferred-VERIFY= (or, under the speedrun preset, route a quick-question gap to the pre-flight Q&A), next task. -4. *Implement* under the project's commit discipline: TDD red→green→refactor, then =/review-code --staged=, fix all Critical/Important findings, then close the task per =todo-format.md='s completion rules. Decompose into as many logical commits as the change needs — size is not capped. If implementation fails partway, leave the tree working, record =failed=, surface it, and continue to the next task. +4. *Implement* under the project's commit discipline: TDD red→green→refactor, then the isolated adversarial review (=publish= Step 1) with its re-review loop, fix all Critical/Important findings, then close the task per =todo-format.md='s completion rules. Decompose into as many logical commits as the change needs — size is not capped. If implementation fails partway, leave the tree working, record =failed=, surface it, and continue to the next task. 5. *Commit autonomy branch:* - =file-only= → surface the diff, do *not* commit. Record =implemented-diff-surfaced=. - =autonomous-commit= → =/voice personal= on the message, commit individually, push per the project's flow. Record =implemented-committed=. @@ -110,7 +110,8 @@ Autonomy changes who approves, not what quality means. Per task, non-negotiable: - *TDD* per =testing.md=: red first, green, refactor. The keystone checklist item already proved the failing test is writable. - *Verification* per =verification.md=: fresh evidence, full suite green before any commit. -- *=/review-code --staged=* before every commit; Critical and Important findings block until fixed. +- *Isolated adversarial review* before every commit, dispatched per the =publish= skill's Step 1 — never an inline self-review, however small the diff. Critical and Important findings block until fixed, and each fix goes back to the *same* reviewer until it approves. Minor findings never earn another round. + - *When the review can't reach approval* — three rounds without it, a finding that recurs after being reported fixed, or a =Needs Discussion= verdict — the unattended run has no one to ask. Record the task =failed= with the standing findings in its result, leave the tree working, and continue to the next task. Never commit past a blocking finding because nobody is awake to adjudicate — an unreviewed commit landing overnight is the outcome this gate exists to prevent. - *=/voice personal=* on every commit message on the =autonomous-commit= path (or the patterns walked inline if the skill is unavailable), message printed inline so the log shows what landed. - *Task closure* per =todo-format.md=: depth-based completion (keyword + =CLOSED:= at level 2, dated rewrite at level 3+). - *One logical change per commit.* A large task becomes several commits, not one omnibus. diff --git a/.ai/workflows/wrap-it-up.org b/.ai/workflows/wrap-it-up.org index d212195..ecd3d22 100644 --- a/.ai/workflows/wrap-it-up.org +++ b/.ai/workflows/wrap-it-up.org @@ -29,6 +29,8 @@ The wrap-up is complete when: The absence of =.ai/session-context.org= is the signal that the last session wrapped up cleanly. Its presence at session start means the previous session was interrupted. +*A helper session meets a shorter list.* Criteria 1 and 2 apply to its own context file (archived under =.ai/sessions/YYYY-MM-DD-HH-MM-<id>-<description>.org=), and 6 applies. Criteria 3, 4, and 5 do not: hygiene, the Linear pass, and all git mutation belong to the primary, so a helper that satisfied criterion 5 would have violated its contract to get there. Step 0 routes this. + * Teardown mode (set from the trigger phrase) The wrap itself — Steps 1 through 5 — is identical in every mode. The trigger phrase only decides what Step 6 does once commit + push and the valediction are done. Resolve the mode from the phrase before starting: @@ -43,7 +45,35 @@ This depends on three functions in =.emacs.d/modules/ai-term.el= (=cj/ai-term-qu * The Workflow -** Step 0: Refuse if sentry is live +** Step 0: Helper branch — a helper wraps only itself + +Resolve first whether this session is a helper, because a helper's wrap is a different and much shorter workflow. Everything from Step 1 down — the hygiene passes, the inbox check, the commit, the push, the clean-tree certificate — is primary-only under the role contract in [[file:helper-mode.org][helper-mode.org]], and running any of it from a helper is exactly the concurrency failure that contract exists to prevent. + +A session is a helper when =AI_HELPER=1= in its environment (=ai --helper= sets it) or when it adopted helper-mode.org this session by instruction. If neither holds, this is a primary: skip to Step 0.5 and wrap normally. + +#+begin_src bash +echo "AI_HELPER=${AI_HELPER:-unset} AI_AGENT_ID=${AI_AGENT_ID:-unset}" +#+end_src + +For a helper, re-run the roster — the answer decides which wrap applies: + +#+begin_src bash +root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" +if [ -x "$root/.ai/scripts/agent-roster" ]; then + "$root/.ai/scripts/agent-roster" "$root"; rc=$? +else + rc=2 +fi +echo "roster rc=$rc" +#+end_src + +Pass the project root explicitly. =agent-roster= defaults to =$PWD= and keeps only agents whose cwd is at or inside that root, so running it from a subdirectory hides a primary sitting at the root — and the "alone" that produces is read below as *orphaned*, which is the one branch that commits and pushes. Capture =rc= inside the branch too: =[ -x … ] && …; echo $?= reports the status of the whole list, so an absent script reads as 1 (others live) rather than 2 (unavailable). + +- *Primary still live (rc 1)* — the normal case. Finalize the =* Summary= in the helper's own context file — same contract as Step 1, KB receipt line included (resolve it with =AI_AGENT_ID=<id> .ai/scripts/session-context-path=), archive it to =.ai/sessions/YYYY-MM-DD-HH-MM-<id>-<description>.org= so it can't collide with the primary's archive name, deliver the valediction, and stop. Do NOT commit, push, or run any hygiene pass. The helper's scoped edits stay in the tree and the primary's next commit carries them along with the archived file — say so in the valediction, so Craig knows the work is real but not yet pushed. +- *Alone (rc 0) — orphaned helper* — the primary exited first, so the git ban lifts: the concurrency that justified it is gone, and stopping here would strand the helper's edits as a dirty tree nobody owns. Run the full wrap below starting at Step 0.5, exactly as a primary would. +- *Roster unavailable (rc 2, or the script absent)* — take the archive-only path, the same as primary-still-live. Leaving work for the next session to commit is recoverable; guessing "orphaned" and committing underneath a live primary is not. + +** Step 0.5: Refuse if sentry is live Before anything else, check whether sentry is running in this project. Sentry holds the working tree on its =sentry/<date>-<host>= branch and commits unattended; wrapping underneath it would archive the session anchor and tear down the buffer while the loop is still firing into it. If sentry's single-runner lock is held, stop and point at the shutdown path: @@ -55,7 +85,7 @@ if [ -x .ai/scripts/agent-lock ] && .ai/scripts/agent-lock status "sentry-$proj" fi #+end_src -The stop-sentry operation (defined in =sentry.org=) owns the shutdown: it cancels the loop, disposes of the branch, and walks the approval queue. Wrap-up carries only this one guard; a =stale= lock (a crashed fire) doesn't block — only a live =held= lock does. +The stop-sentry operation (defined in =sentry.org=) owns the shutdown: it cancels the loop, disposes of the branch, and walks the approval queue. Wrap-up carries only this one guard; a =stale= lock (a crashed cycle) doesn't block — only a live =held= lock does. ** Step 1: Finalize the Summary diff --git a/claude-rules/commits.md b/claude-rules/commits.md index e3f75a8..3283b0a 100644 --- a/claude-rules/commits.md +++ b/claude-rules/commits.md @@ -91,6 +91,40 @@ Edge case: when one of these files *is* the change (a commit in the rulesets rep **Tooling-path enumeration is the same leak.** Citing a rule as authority isn't the only way the tooling layer leaks into history. A commit whose *content* must name these paths — a `.gitignore` adding `.claude/`, `CLAUDE.md`, `.ai/` — has unavoidable, correct file content, but its *message prose* must not enumerate them ("chore: ignore .claude tooling, CLAUDE.md, and session files"). On a public or shared-remote repo that enumeration exposes the tooling layer's structure in the log just as a citation would. Name the category instead: "chore: extend gitignore for local tooling and build artifacts". The same holds for any incidental mention, not only `.gitignore` commits. Two exemptions: a commit whose change *is* one of these files (the edge case above), and private single-user repos with no shared remote, where the history is the project and there's no third party to leak to. +## Write in the first person, as Craig + +Everything authored in or about this repo is first person: code comments, commit +messages, PR descriptions, PR review comments, and any note that lands in the +repo or its history. State a choice as a choice — "I swept the copies rather +than repairing them, because a drifted copy outranked the global rule" beats +"the copies are swept rather than repaired." + +**The "I" is Craig.** He is the author of record on every commit, comment, and +review in his repos, and these artifacts go out under his name. So the voice is +his, writing about his own work — not an agent narrating what it did on his +behalf. Never write the agent into the prose as a separate party: no "Craig +asked me to", no "I filed this for Craig", no "needs Craig's decision". Where a +decision is still open, it is *his* open decision, written as "I haven't decided +whether…" or "this needs a call I haven't made yet." + +The same holds for anyone else's work. Name them ("Kostya's PR #116 did X"), +because they are a third party. Craig is not. + +Third-person constructions like "This change introduces X" or "This PR restores +Y" read as press-release self-narration. The commit is the change, so it does +not need announcing. + +**The one carve-out: code is the actor when describing behavior.** A comment +saying *what the code does* stays third person, because the subject genuinely +is the code and not me — "the sweep only fires when the global rule exists", +"the guard rejects a malformed payload". First person is for the decision +behind it, third person for the behavior itself. Both often belong in the same +comment: what it does, then why I chose it. + +This is the rule the publish flow already applied to commit bodies. It lives +here because code comments get written constantly and the publish skill is not +loaded then. + ## The publish flow lives in the `publish` skill Everything about *how* a commit, PR, or review comment gets written, reviewed, diff --git a/claude-rules/subagents.md b/claude-rules/subagents.md index 8578dea..e52d906 100644 --- a/claude-rules/subagents.md +++ b/claude-rules/subagents.md @@ -34,6 +34,66 @@ This is the same boundary the "Don't Subagent At All" section and the "Subagenting trivial work" anti-pattern draw; treat it as an explicit gate at dispatch time. +Every size-based rule in this file — the cost gate here, "Don't Subagent At +All", the trivial-work anti-pattern — is subject to the isolation override +below. + +## Isolation Override — When Size Doesn't Gate + +Every size heuristic in this file rests on one assumption: that the main +thread could do the task itself just as well, so the only question is +whether delegating is worth the overhead. When that assumption fails, the +heuristics don't apply, and a five-line task can require a subagent that a +five-hundred-line one wouldn't. + +The assumption fails whenever **the main thread is structurally disqualified +from the task** — not slower at it, disqualified. The test: would the main +thread's own context make its answer *less* trustworthy? If holding the +context is what corrupts the judgment, then doing it inline doesn't save the +overhead, it destroys the result. The isolation *is* the deliverable, and +"it's only a small diff" is not an argument against it. + +**The standing instance is the pre-commit code review** (`publish` skill, +Step 1). The author cannot review their own change, because a self-review +checks the diff against the author's own model of it and cannot check the +model. Errors that survive a self-review are the ones that were never in the +diff — an inherited scope, an estimated blast radius, a fix correct for the +case in mind and wrong for the one never considered. So that review is +dispatched on *every* commit including a one-line one, and the ~10-tool-call +floor, the single-function rule, and the trivial-work anti-pattern are all +overridden there by design. + +Other cases with the same shape: verifying a claim the main thread already +committed to in conversation, and any second opinion where the first opinion +is already in context. If you find yourself reasoning "I already know the +answer, so a subagent is wasteful," check whether already knowing it is the +problem. + +This override widens *what* gets dispatched. Scope, constraints, and output +format are still required, and arguably matter more here, since an isolated +agent can't fall back on shared context to fill a gap. + +**Field 2 of the Prompt Contract inverts under this override, and the +inversion is the whole point.** Normally field 2 says to paste the relevant +output verbatim and include what you learned in earlier turns. Do that for an +isolation dispatch and you hand over the very model you spawned the agent to +escape — a reviewer given your findings reviews your findings. So for an +isolation dispatch, field 2 is *the artifact under test and the independent +record of what was asked, and nothing else*: the diff, a one-line claim of +what it does, and the ticket or plan where one exists. The conversation, the +rationale, and the dead ends are withheld on purpose. + +Keep the requirement source in. A ticket is not your model of the change; it +was written before the work, usually by someone else, and it is the only +thing that can contradict your claim about your own diff. + +**The output is a judgment, so the review gate resolves differently.** The +Review-Gate Cadence below says subagent output is a claim to be verified +before moving on, which is right when the deliverable is *work*. When the +deliverable is *a judgment about your work*, verifying it against your own +reading reinstates exactly the bias the dispatch removed. Disagreement goes +to the user to adjudicate, not back to the author's own judgment. + ## When to Spawn a Subagent ### Parallel-safe (spawn multiple in parallel) @@ -63,11 +123,15 @@ at dispatch time. ### Don't Subagent At All +Unless the Isolation Override applies — these are efficiency rules, and they +lapse when the main thread's own context is what makes its answer untrustworthy. + - **The target is already known** and the work fits in under ~10 tool calls. - **Single-function logic** — one Read + one Edit is faster than briefing an agent. - **You can see the answer from context** — don't spawn a researcher for - something already on screen. + something already on screen. (The inverse of this one is the override's + clearest case: when *having* seen it is the disqualification, dispatch.) ## Prompt Contract @@ -138,7 +202,11 @@ fix), then dispatch the fix with a specific contract. - **Retrying a failed subagent task in the orchestrator** — pollutes context. Dispatch a fix agent instead. - **Subagenting trivial work** — one Read + one Edit doesn't need an - agent; spawn overhead exceeds benefit. + agent; spawn overhead exceeds benefit. Except under the Isolation + Override, where a one-line diff still gets its own reviewer. +- **Reviewing your own change inline** — the mirror-image failure, and the + more expensive one. Skipping a dispatch to save overhead on a small diff + costs a review that could only have come from outside your context. - **Skipping review between tasks** — compounding bugs are much harder to unwind than any single bug. - **Letting the agent decide scope** — "figure out what needs changing" diff --git a/claude-rules/testing.md b/claude-rules/testing.md index 81bd391..dd15282 100644 --- a/claude-rules/testing.md +++ b/claude-rules/testing.md @@ -16,377 +16,30 @@ TDD is the default workflow for all code, including demos and prototypes. **Writ Do not skip TDD for demo code. Demos build muscle memory — the habit carries into production. -### Understand Before You Test -Before writing tests, invest time in understanding the code: +## Test Categories — required for all code -1. **Explore the codebase** — Read the module under test, its callers, and its dependencies. Understand the data flow end to end. -2. **Identify the root cause** — If fixing a bug, trace the problem to its origin. Don't test (or fix) surface symptoms when the real issue is deeper in the call chain. -3. **Reason through edge cases** — Consider boundary conditions, error states, concurrent access, and interactions with adjacent modules. Your tests should cover what could actually go wrong, not just the obvious happy path. +Every unit under test needs all three, not just the happy path: -### Adding Tests to Existing Untested Code +1. **Normal** — standard inputs, common workflows, typical volumes. +2. **Boundary** — zero, one, max, empty vs null, single-element collections, unicode, very long input, timezone and date edges. +3. **Error** — invalid input, type mismatches, network failure, missing parameters, permission denied, resource exhaustion, malformed data. -When working in a codebase without tests: +The negative and boundary cases are the ones that find bugs. A unit with only +Normal coverage is not tested, it is demonstrated. -1. Write a **characterization test** that captures current behavior before making changes -2. Use the characterization test as a safety net while refactoring -3. Then follow normal TDD for the new change +## The rest of the standard lives in the `testing-standards` skill -A characterization test asserts what the code *actually does* right now, not -what it *should* do. Write it by running the code against a fixed input, -reading the exact value or effect it currently produces, and asserting that -value — Feathers' recipe is to assert something you know is wrong, run it, and -paste the real value out of the failure. You don't need to know the correct -answer to write one; you record the observed one. That's what makes it -mechanical enough to bring a large untested surface under test without -re-deriving each unit's spec. +Characterization tests for untested code, the per-category detail, combinatorial +and property-based and mutation testing, organization and the pyramid, +integration-test rules, naming, the test-quality rules (independence, +determinism, mocking boundaries, signs of overmocking), the +refactor-when-tests-are-hard principle, coverage targets, the spike exception, +and the anti-pattern list are all in the `testing-standards` skill. Load it when +writing tests. -**Characterize with the same Normal/Boundary/Error set as any unit** (the three -categories below), not one happy-path capture per function. On a characterization -test the negative and boundary cases are the ones that find bugs: untested legacy -code is weakest exactly at the empty input, the malformed value, the missing -upstream, and pinning what it *currently* does there writes the wrong behavior -down in black and white, where it becomes a bug you can see and decide on. When a -pinned case turns out to be a bug rather than behavior worth preserving, that one -test graduates from "record current" to "assert correct" and you fix the code. -The happy-path case is the regression net; the negative and boundary cases are -the audit. - -Bugs that live *inside* a unit are caught by this three-category set; bugs in how -units compose — ordering, shared state handed between them — are invisible to any -per-unit test and need a functional/integration test over the composed path (see -Integration Tests below and the pyramid). - -## Test Categories (Required for All Code) - -Every unit under test requires coverage across three categories: - -### 1. Normal Cases (Happy Path) -- Standard inputs and expected use cases -- Common workflows and default configurations -- Typical data volumes - -### 2. Boundary Cases -- Minimum/maximum values (0, 1, -1, MAX_INT) -- Empty vs null vs undefined (language-appropriate) -- Single-element collections -- Unicode and internationalization (emoji, RTL text, combining characters) -- Very long strings, deeply nested structures -- Timezone boundaries (midnight, DST transitions) -- Date edge cases (leap years, month boundaries) - -### 3. Error Cases -- Invalid inputs and type mismatches -- Network failures and timeouts -- Missing required parameters -- Permission denied scenarios -- Resource exhaustion -- Malformed data - -## Combinatorial Coverage - -For functions with 3+ parameters that each take multiple values (feature-flag -combinations, config matrices, permission/role interactions, multi-field -form validation, API parameter spaces), the exhaustive test count explodes -(M^N) while 3-5 ad-hoc cases miss pair interactions. Use **pairwise / -combinatorial testing** — generate a minimal matrix that hits every 2-way -combination of parameter values. Empirically catches 60-90% of combinatorial -bugs with 80-99% fewer tests. - -Invoke `/pairwise-tests` on the offending function; continue using `/add-tests` -and the Normal/Boundary/Error discipline for the rest. The two approaches -complement: pairwise covers parameter *interactions*; category discipline -covers each parameter's individual edge space. - -Skip pairwise when: the function has 1-2 parameters (just write the cases), -the context requires *provably* exhaustive coverage (regulated systems — document -in an ADR), or the testing target is non-parametric (single happy path, -performance regression, a specific error). - -## Escalation Beyond Category and Pairwise - -The Normal/Boundary/Error categories and the pairwise matrix are the default -discipline. Two further techniques escalate beyond them — reach for them when -the default leaves a gap, not on every unit. - -### Property-Based Testing - -When an invariant holds across a broad input domain — round-trips -(`decode(encode(x)) == x`), idempotence (`f(f(x)) == f(x)`), ordering -invariants (output is always sorted), or any "output always satisfies X" — -generate inputs and assert the property instead of enumerating cases. The -generator explores corners you wouldn't think to write by hand, and a -failing case shrinks to a minimal reproducer. Use the standard tool for the -language (Hypothesis for Python, fast-check for JS, proptest for Rust). -State the property as the test name and let the framework supply the inputs. - -Reach for this when the behavior is a law over a domain rather than a fixed -set of examples. Keep category-discipline cases for the specific edges that -must always hold; the property test covers the space between them. - -### Mutation Testing - -When line coverage is high but you suspect the assertions are thin — tests -that execute the code without checking its output, or that pass with a -function body replaced by a stub — use mutation testing to measure whether -the suite actually kills injected faults. The tool flips conditionals, swaps -operators, and deletes statements, then reruns the suite; a surviving mutant -is a fault the tests didn't catch. Use mutmut or cosmic-ray for Python, -Stryker for JS. High line coverage with a low mutation score means weak -assertions, not a tested codebase. - -Reach for this on critical logic where coverage looks reassuring but you -want evidence the tests would fail on a regression. It's a diagnostic, not a -gate on every change — mutation runs are slow. - -## Test Organization - -Typical layout: - -``` -tests/ - unit/ # One test file per source file - integration/ # Multi-component workflows - e2e/ # Full system tests -``` - -Per-language files may adjust this (e.g. Elisp collates ERT tests into -`tests/test-<module>*.el` without subdirectories). - -### Testing Pyramid - -Rough proportions for most projects: -- Unit tests: 70-80% (fast, isolated, granular) -- Integration tests: 15-25% (component interactions, real dependencies) -- E2E tests: 5-10% (full system, slowest) - -Don't duplicate coverage: if unit tests fully exercise a function's logic, -integration tests should focus on *how* components interact — not repeat the -function's case coverage. - -## Integration Tests - -Integration tests exercise multiple components together. Two rules: - -**The docstring names every component integrated** and marks which are real vs -mocked. Integration failures are harder to pinpoint than unit failures; -enumerating the participants up front tells you where to start looking. - -Example: - -``` -def test_integration_refund_during_sync_updates_ledger_atomically(): - """Refund processed mid-sync updates order and ledger in one transaction. - - Components integrated: - - OrderService.refund (entry point) - - PaymentGateway.reverse (MOCKED — returns success) - - Ledger.credit (real) - - db.transaction (real) - - Validates: - - Refund rolls back if ledger write fails - - Both tables updated or neither - """ -``` - -**Write an integration test when** multiple components must work together, -state crosses function boundaries, or edge cases combine. **Don't** when -single-function behavior suffices, or when mocking would erase the interaction -you meant to test. - -## Naming Convention - -- Unit: `test_<module>_<function>_<scenario>_<expected>` -- Integration: `test_integration_<workflow>_<scenario>_<outcome>` - -Examples: -- `test_cart_apply_discount_expired_coupon_raises_error` -- `test_integration_order_sync_network_timeout_retries_three_times` - -Languages that prefer camelCase, kebab-case, or other conventions keep the -structure but use their idiom. Consistency within a project matters more than -the specific case choice. - -## Test Quality - -### Independence -- No shared mutable state between tests -- Each test runs successfully in isolation -- Explicit setup and teardown - -### Determinism -- Never hardcode dates or times — generate them relative to `now()` -- No reliance on test execution order -- No flaky network calls in unit tests -- Time/clock-mocking helpers must avoid two recurring failure modes: - - *Infinite recursion.* The helper must not call the primitive it's - replacing. If the mock for `now()` calls `now()`, the test stack - overflows. Compute the mock value from a fixed source (a captured - instant, an injected fake clock). - - *Scope-shadowing without reach.* A mock that only exists inside - the test function won't affect production code that reads the - symbol through its canonical path. Replace the symbol at its - definition site (monkey-patch the module attribute in Python, - redefine the global in Lisp, swap the package-level binding in - Go, replace the named export in JavaScript) — or inject a fake - via dependency-inversion. Don't lean on scope-shadowing - primitives (Lisp `let`, Python local rebind, JS shadowed `let`) - that fence the mock to the test's lexical scope; production code - won't see them and the test passes against the real clock. - -### Performance -- Unit tests: <100ms each -- Integration tests: <1s each -- E2E tests: <10s each -- Mark slow tests with appropriate decorators/tags - -### Mocking Boundaries -Mock external dependencies at the system boundary: -- Network calls (HTTP, gRPC, WebSocket) -- File I/O and cloud storage -- Time and dates -- Third-party service clients - -Never mock: -- The code under test -- Internal domain logic -- Framework behavior (ORM queries, middleware, hooks, buffer primitives) - -### Signs of Overmocking - -Ask yourself: - -- Would this test still pass if I replaced the function body with `raise NotImplementedError` (or equivalent)? If yes, the mocks are doing the work — you're testing mocks, not code. -- Is the mock more complex than the function being tested? Smell. -- Am I mocking internal string / parsing / decoding helpers? Those aren't boundaries — they're the work. -- Does the test break when I refactor without changing behavior? Good tests survive refactors; overmocked ones couple to implementation. - -When tests demand heavy internal mocking, the fix isn't better mocks — it's -restructuring the code (see *If Tests Are Hard to Write* below). - -### Testing Code That Uses Frameworks - -When a function mostly delegates to framework or library code, test *your* -integration logic: -- ✓ "I call the library with the right arguments in the right context" -- ✓ "I handle its return value correctly" -- ✗ "The library works in 50 scenarios" — trust it; it has its own tests - -For polyglot behavior (e.g., comment handling across C/Java/Go/JS), test 2-3 -representative modes thoroughly plus a minimal smoke test in the others. -Exhaustive permutations are diminishing returns. - -### Test Real Code, Not Copies - -Never inline or copy production code into test files. Always `require`/`import` -the module under test. Copied code passes even when production breaks — the -bug hides behind the duplicate. - -Mock dependencies at their boundary; exercise the real function body. - -### Error Behavior, Not Error Text - -Test that errors occur with the right type; don't assert exact wording: -- ✓ Right exception type (`pytest.raises(ValueError)`, `(should-error ... :type 'user-error)`) -- ✓ Regex on values the message *must* contain (e.g., the offending filename) -- ✗ `assert str(e) == "File 'foo' not found"` — breaks when prose changes even though behavior is unchanged - -Production code should emit clear, contextual errors. Tests verify the -behavior (raised, caught, returned nil) and values that must appear — not the -prose. - -## If Tests Are Hard to Write, Refactor the Code - -If a test needs extensive mocking of internal helpers, elaborate fixture -scaffolding, or mocks that recreate the function's own logic, the production -code needs restructuring — not the test. - -Signals: -- Deep nesting (callbacks inside callbacks) -- Long functions doing multiple things ("fetch AND parse AND decode AND save") -- Tests that mock internal string / parsing / I/O helpers -- Tests that break on refactors with no behavior change - -Fix: extract focused helpers (one responsibility each), test each in isolation -with real inputs, compose them in a thin outer function. Several small unit -tests plus one composition test beats one monster test behind a wall of mocks. - -When the untestable function is legacy code you're hardening, this extraction -**is** the hardening — not a detour around it. A function whose boundary or -error case can't be exercised without mocking the world (a shell function that -calls `tmux`/`git` directly, a handler that reaches straight into I/O) can't be -characterized, so you can't refactor it safely and you can't pin its edge -behavior. Extracting the pure decision logic into a helper that takes plain -inputs and returns a plain result makes that logic characterizable with the full -Normal/Boundary/Error set; the I/O calls become a thin wrapper you cover once -with a single composition test. "It needs too much mocking to test" is therefore -never a reason to skip the boundary and error cases — it's the signal to reshape -the function so those cases are writable. - -## Coverage Targets - -- Business logic and domain services: **90%+** -- API endpoints and views: **80%+** -- UI components: **70%+** -- Utilities and helpers: **90%+** -- Overall project minimum: **80%+** - -New code must not decrease coverage. PRs that lower coverage require justification. - -## TDD Discipline - -TDD is non-negotiable. These are the rationalizations agents use to skip it — don't fall for them: - -| Excuse | Why It's Wrong | -|--------|----------------| -| "This is too simple to need a test" | Simple code breaks too. The test takes 30 seconds. Write it. | -| "I'll add tests after the implementation" | You won't, and even if you do, they'll test what you wrote rather than what was needed. Test-after validates implementation, not behavior. | -| "Let me just get it working first" | That's not TDD. If you can't write a failing test, you don't understand the requirement yet. | -| "This is just a refactor" | Refactors without tests are guesses. Write a characterization test first, then refactor while it stays green. | -| "I'm only changing one line" | One-line changes cause production outages. Write a test that covers the line you're changing. | -| "The existing code has no tests" | Start with a characterization test. Don't make the problem worse. | -| "This is demo/prototype code" | Demos build habits. Untested demo code becomes untested production code. | -| "I need to spike first" | Spikes are fine — under the protocol below. Throw the spike away, then write the first failing test before productionizing. | - -If you catch yourself thinking any of these, stop and write the test. - -### The Spike Exception (Disciplined) - -TDD stays the default. The one sanctioned way to write code before a test is -a spike — exploratory code that answers "is this approach even viable?" when -you can't yet write a meaningful failing test because the shape of the -solution is unknown. A spike is disciplined only when all three hold: - -1. **Timebox it.** Set a limit before starting (an hour, an afternoon) and - stop when it's up. An open-ended spike is just untested implementation - wearing a different name. -2. **Do not commit spike code.** The spike is a learning artifact, not a - deliverable. It never enters the branch history. Keep it in a scratch - file or a throwaway worktree. -3. **Throw the spike away, then start with a failing test.** Once the spike - has answered the viability question, delete it. Write the first failing - test against the now-understood behavior, then productionize under normal - Red/Green/Refactor. The production code is written test-first even though - the exploration wasn't — you don't promote the spike into production by - bolting tests on after. - -The spike buys understanding, not code. If you find yourself keeping the -spike because rewriting it feels wasteful, the timebox was too long or the -problem was tractable enough to TDD from the start. - -## Anti-Patterns (Do Not Do) - -- Hardcoded dates or timestamps (they rot) -- Testing implementation details instead of behavior -- Mocking the thing you're testing -- Mocking internal helpers (string ops, parsing, decoding) — those are the work -- Inlining production code into test files — always `require` / `import` the real module -- Asserting exact error-message text instead of type + key values -- Shared mutable state between tests -- Non-deterministic tests (random without seed, network in unit tests) -- Testing framework behavior instead of your code -- Ignoring or skipping failing tests without a tracking issue +What stays here is what has to be true before any code is written, which is when +no skill has been summoned yet: test first, and cover all three categories. ## Content scope diff --git a/claude-rules/todo-format.md b/claude-rules/todo-format.md index 58570b1..8038b98 100644 --- a/claude-rules/todo-format.md +++ b/claude-rules/todo-format.md @@ -139,7 +139,8 @@ measurable one: against the list, so "covered" is checkable where "found everything" isn't. 2. **Net the behavior.** Bring the surface under characterization tests - (Normal/Boundary/Error per unit — see `testing.md`) before changing + (Normal/Boundary/Error per unit — see `testing.md`, and the + `testing-standards` skill for the characterization recipe) before changing anything. This is the objective floor: writing a characterization test is mechanical (record what the code does, not what it should), so it scales across the surface, and it doubles as the safety net that makes any diff --git a/claude-templates/.ai/protocols.org b/claude-templates/.ai/protocols.org index f4eefed..b291d9e 100644 --- a/claude-templates/.ai/protocols.org +++ b/claude-templates/.ai/protocols.org @@ -106,7 +106,7 @@ The epoch is baked into the id by the spawner, never minted inside =session-cont Resolve the path with =.ai/scripts/session-context-path= rather than hardcoding =.ai/session-context.org=; it prints the right path for the current =AI_AGENT_ID=. Fall back to =.ai/session-context.org= if the script isn't present (older checkouts mid-sync). Everything below — the record/recovery purpose, the update triggers, the startup existence check, the wrap-up rename — operates on that resolved path. The prose says "session-context.org" as the default name; read it as "the resolved active path" when =AI_AGENT_ID= is set. -A helper instance (a second agent running in this project while a primary session is live) follows a different contract: it skips the pulls and rsync, makes only scoped single-heading edits to shared files, leaves all git mutation to the primary, and wraps up by archiving its own context file without committing. The full rules — read/write tiers, data-integrity, light startup, helper wrap-up — live in [[file:workflows/helper-mode.org][workflows/helper-mode.org]]. A session is a helper only when something routes it there (the =ai --helper= launcher, startup's roster check, or an explicit "you are a helper" instruction); the routing itself ships behind the helper-instance feature gate and isn't live yet. +A helper instance (a second agent running in this project while a primary session is live) follows a different contract: it skips the pulls and rsync, makes only scoped single-heading edits to shared files, leaves all git mutation to the primary, and wraps up by archiving its own context file without committing. The full rules — read/write tiers, data-integrity, light startup, helper wrap-up — live in [[file:workflows/helper-mode.org][workflows/helper-mode.org]]. A session is a helper only when something routes it there: the =ai --helper= launcher (live — it checks the roster, assigns the id, and opens the helper in its own tmux window) or an explicit "you are a helper" instruction. Startup's roster check is *not* built, so a bare =claude= launched into a project that already has a live session will run full primary startup regardless. Launch helpers with =ai --helper=. This file serves two purposes with one mechanism: 1. *Crash recovery* — if the session dies mid-work, the live file is all that's left. On 2026-01-22 a session crashed during a 20-minute design discussion and all context was lost because this file wasn't being updated. @@ -270,7 +270,9 @@ The queue lives in the session anchor (=.ai/session-context.org=) under a =* Bef Three ways to access Craig's calendars: Google Calendar MCP (preferred, both personal + work accounts), gcalcli (fallback, personal only), Emacs org files (read-only viewer). -For tool recipes, authentication details, and credentials, see [[file:references/calendar-reference.org][calendar-reference.org]]. +For tool recipes and account details, read the calendar workflows in =.ai/workflows/=: =add-calendar-event.org=, =edit-calendar-event.org=, =delete-calendar-event.org=, =read-calendar-events.org=. They carry the MCP tool names, both account ids, the gcalcli fallback, and the conflict-check discipline. + +Credentials are needed only for a re-auth Craig performs himself. The MCP bundle's =mcp/README.org= in the rulesets repo is the authority: =gcp-oauth.keys.json= is gitignored and regenerated at install from a base64 var in the bundle, never committed. Named in prose rather than linked, because that path isn't synced into consuming projects. ** GPG Keys diff --git a/claude-templates/.ai/references/calendar-reference.org b/claude-templates/.ai/references/calendar-reference.org deleted file mode 100644 index 5791b08..0000000 --- a/claude-templates/.ai/references/calendar-reference.org +++ /dev/null @@ -1,66 +0,0 @@ -#+TITLE: Calendar Reference -#+AUTHOR: Craig Jennings - -Tool recipes, authentication, and credentials for Craig's calendar -setup. Three access methods, in order of preference. - -* Google Calendar MCP Server (preferred for all calendar operations) - -Craig has the =@cocal/google-calendar-mcp= MCP server configured at user scope (=~/.claude.json=). It provides full read/write access to Google Calendar via MCP tools. - -Two accounts are authenticated: -- *personal* — craigmartinjennings@gmail.com (primary: "Craig Google") -- *work* — craig.jennings@deepsat.com (primary: "Craig Deepsat") - -MCP tools available: -- =list-events=, =search-events=, =get-event= — read events -- =create-event=, =create-events= — add events -- =update-event= — modify events -- =delete-event= — remove events -- =list-calendars=, =list-colors= — calendar metadata -- =get-freebusy= — check availability -- =manage-accounts= — add/remove/list authenticated accounts -- =respond-to-event= — accept/decline invitations -- =get-current-time= — current time in any timezone - -Use =account_id: "personal"= or =account_id: "work"= to specify which account. - -Default calendar for adding events: "Craig Google" (personal account). - -Calendar workflows are available alongside this reference: add-calendar-event, edit-calendar-event, delete-calendar-event, read-calendar-events. - -If re-authentication is needed: -- Use the =manage-accounts= MCP tool with =action: "add"= and the account nickname -- OAuth credentials: =~/projects/homelab/assets/gcp-oauth.keys.json= -- Google Cloud app is in production mode (tokens don't expire after 7 days) -- See =~/projects/homelab/.ai/gcalcli-setup.org= for Google Cloud project details - -* gcalcli (fallback for personal account only) - -Craig has =gcalcli= installed via pipx, authenticated to his personal Google account only. - -#+begin_src bash -gcalcli agenda # upcoming events -gcalcli calw # weekly view -gcalcli add --title "..." --when "..." --duration "60" # add event -gcalcli search "..." # search events -gcalcli delete "..." # delete event -#+end_src - -Use =--calendar "Craig Google"= when adding events. - -gcalcli does NOT have access to the work (DeepSat) calendar. Use the MCP server for work calendar operations. - -If gcalcli needs re-authentication, credentials are stored in the homelab project: =~/projects/homelab/assets/gcalcli-client-secret.json.gpg= (GPG encrypted). - -* Emacs org files (read-only, for viewing schedules) - -Craig's calendars are at: =~/.emacs.d/data/*cal.org= (gcal.org, dcal.org, pcal.org) - -These files are **READ-ONLY** — NEVER add anything to them. - -Use this to: -- Check meeting times and schedules -- Verify when events occurred -- See what's upcoming -- Note: only updated periodically when Emacs is running — may be stale diff --git a/claude-templates/.ai/scripts/sync-templates b/claude-templates/.ai/scripts/sync-templates new file mode 100755 index 0000000..b9769f3 --- /dev/null +++ b/claude-templates/.ai/scripts/sync-templates @@ -0,0 +1,131 @@ +#!/usr/bin/env bash +# sync-templates — copy rulesets' canonical .ai/ templates into this project. +# +# Extracted verbatim from startup.org Phase A step 3 (2026-07-31). This is the +# mechanism that distributes every workflow, protocol and script change to every +# project, and until the extraction it was untested inline bash running in every +# session. The extraction exists so the guard changes that follow can be tested +# before they reach a file whose failure mode is "no project starts". +# +# Behavior is deliberately identical to the inline block it replaces, including +# its rough edges. Anything that looks like a defect here is characterized by a +# test rather than fixed in passing — a change of behavior belongs in its own +# commit, not smuggled into an extraction. +# +# Usage: sync-templates [project-root] (default: $PWD) +# Output: one line naming the outcome, matching the previous inline wording +# Exit: 0 always, as the inline block did — the outcome is on stdout +# +# Two guards, and they work differently. One withholds files; the other skips +# the whole run: +# +# Rulesets dirty under the synced paths → withhold exactly those files. +# rsync -a --delete copies the working tree by disk presence, so an in-flight +# edit in rulesets would otherwise land downstream as drift the project never +# authored. Each dirty path becomes an --exclude, which rsync honors on both +# sides: the file is neither overwritten nor deleted downstream, and every +# clean file still propagates. This was a global skip until 2026-07-31, which +# meant one uncommitted file in rulesets froze every template for every +# project until it was committed. +# +# Project branch behind its upstream → skip the whole sync. Syncing onto a +# stale committed .ai/ baseline measures the diff against old content, so it +# comes out huge and conflicts once the branch reconciles to an upstream that +# already carries the newer templates. This one stays all-or-nothing because +# the staleness is in the destination, not in any particular source file. +# +# The rulesets location is injectable (SYNC_RULESETS_DIR) so the guards can be +# exercised against a fixture instead of the real checkout. + +rs="${SYNC_RULESETS_DIR:-$HOME/code/rulesets}" +proj="${1:-$PWD}" + +cd "$proj" || { + echo "sync-templates: cannot enter '$proj'" >&2 + exit 0 +} + +# The dirty set under the synced paths, one repo-relative path per line. +# core.quotePath=false keeps a non-ASCII filename literal instead of \xNN-escaped, +# so the path we build an --exclude from is the path on disk. +synced_dirty=$(cd "$rs" && git -c core.quotePath=false status --porcelain -- \ + claude-templates/.ai/protocols.org \ + claude-templates/.ai/workflows/ \ + claude-templates/.ai/scripts/ 2>/dev/null) + +# Turn that set into per-rsync --exclude flags rather than a global skip. An +# excluded path is neither overwritten nor deleted on the receiving side, so an +# in-flight edit stays in-flight while every file it doesn't touch propagates +# normally. The all-or-nothing skip this replaces is what caused the 2026-07-30 +# outage: one uncommitted workflow file withheld every template from every +# project for a full day. +protocols_dirty=0 +wf_excludes=() +sc_excludes=() +withheld=() + +while IFS= read -r line; do + [ -z "$line" ] && continue + path="${line:3}" + # A rename reports "old -> new". Withhold both sides: the new name is + # half-landed, and sweeping the old copy downstream would delete a file the + # project still runs while the rename sits uncommitted. + if [[ "$path" == *" -> "* ]]; then + paths=("${path%% -> *}" "${path##* -> }") + else + paths=("$path") + fi + for p in "${paths[@]}"; do + p="${p%\"}"; p="${p#\"}" + case "$p" in + claude-templates/.ai/protocols.org) + # A single-file rsync has nothing to exclude within, so this one + # transfer is skipped outright while the other two still run. + protocols_dirty=1 + withheld+=("$p") + ;; + claude-templates/.ai/workflows/*) + # Leading / anchors the pattern to the transfer root, so a dirty + # workflows/foo.org can't also suppress scripts/tests/foo.org. + wf_excludes+=("--exclude=/${p#claude-templates/.ai/workflows/}") + withheld+=("$p") + ;; + claude-templates/.ai/scripts/*) + sc_excludes+=("--exclude=/${p#claude-templates/.ai/scripts/}") + withheld+=("$p") + ;; + esac + done +done <<< "$synced_dirty" + +# behind==0 (up-to-date or ahead-only) means HEAD contains all of upstream, so +# the baseline is current. No upstream (new/unpushed branch) → rev-list fails → +# proj_behind stays 0 → the sync runs. +proj_behind=0 +if [ -d .git ]; then + counts=$(git rev-list --left-right --count '@{u}...HEAD' 2>/dev/null) \ + && [ "$(printf '%s' "$counts" | cut -f1)" -gt 0 ] 2>/dev/null \ + && proj_behind=1 +fi + +if [ "$proj_behind" -eq 1 ]; then + echo "project branch is behind upstream — skipping .ai/ sync this session (templates never land on a stale baseline; the sync runs once the branch is current)" +else + [ "$protocols_dirty" -eq 0 ] && rsync -a "$rs/claude-templates/.ai/protocols.org" .ai/protocols.org + rsync -a --delete "${wf_excludes[@]}" "$rs/claude-templates/.ai/workflows/" .ai/workflows/ + # Running rulesets' own pytest leaves these in the canonical scripts/tests/, + # and rsync -a copies by disk presence regardless of .gitignore, so without + # the excludes every project's tree collects machine-specific cache files. + rsync -a --delete --exclude='__pycache__' --exclude='.pytest_cache' --exclude='*.pyc' \ + "${sc_excludes[@]}" "$rs/claude-templates/.ai/scripts/" .ai/scripts/ + # Known false-success path, inherited and characterized rather than fixed + # here: this line prints unconditionally, so a run where all three rsyncs + # failed (an absent canonical source, say) still reports a successful sync. + # A last-synced manifest must not be written from this branch as it stands — + # it would stamp success onto a sync that did nothing. + echo ".ai/ synced from templates" + if [ ${#withheld[@]} -gt 0 ]; then + echo " withheld — uncommitted in rulesets, lands once committed:" + printf ' %s\n' "${withheld[@]}" + fi +fi diff --git a/claude-templates/.ai/scripts/tests/sync-templates.bats b/claude-templates/.ai/scripts/tests/sync-templates.bats new file mode 100644 index 0000000..6651c99 --- /dev/null +++ b/claude-templates/.ai/scripts/tests/sync-templates.bats @@ -0,0 +1,319 @@ +#!/usr/bin/env bats +# Characterization tests for sync-templates — the mechanism that distributes +# every template change to every project. +# +# These pin CURRENT behavior (record-not-spec) ahead of the guard changes the +# 2026-07-30 propagation incident calls for. That incident is what these exist +# for: an uncommitted edit in rulesets silently blocked all three rsyncs for a +# whole day, and five workflow files went stale in one downstream project alone +# with nothing anywhere reporting it. Any change to this script's guards has to +# come with a red test here first. +# +# Everything runs against fixture directories via SYNC_RULESETS_DIR, so no test +# touches the real rulesets checkout or any real project. + +setup() { + # This suite lives beside the script it tests and travels with it, so it + # resolves the script relative to itself rather than to a repo root. + SYNC="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/sync-templates" + WORK="$(mktemp -d)" + RS="$WORK/rulesets" + PROJ="$WORK/proj" + export SYNC_RULESETS_DIR="$RS" + + # A minimal rulesets fixture: a git repo with the three synced source paths. + mkdir -p "$RS/claude-templates/.ai/workflows" "$RS/claude-templates/.ai/scripts" + printf 'canonical protocols\n' > "$RS/claude-templates/.ai/protocols.org" + printf 'canonical startup\n' > "$RS/claude-templates/.ai/workflows/startup.org" + printf 'canonical helper\n' > "$RS/claude-templates/.ai/scripts/helper" + # Real rulesets gitignores the python cache paths, so they never make the + # tree dirty. Without this the fixture diverges from production in a way + # that silently disarms the exclusion test: the cache files read as + # untracked, guard one fires, the sync never runs, and assertions that the + # cache did NOT arrive pass because nothing arrived at all. + printf '__pycache__/\n.pytest_cache/\n*.pyc\n' > "$RS/.gitignore" + _mk_repo "$RS" + + # A consuming project with the destination dirs. + mkdir -p "$PROJ/.ai/workflows" "$PROJ/.ai/scripts" +} + +teardown() { rm -rf "$WORK"; } + +_mk_repo() { + local d="$1" + git init -q "$d" + git -C "$d" config user.email t@example.com + git -C "$d" config user.name tester + git -C "$d" config commit.gpgsign false + git -C "$d" config gc.auto 0 + git -C "$d" config maintenance.auto false + git -C "$d" add -A + # --allow-empty: the project fixture holds only empty directories, which git + # has nothing to commit, and these tests need it to be a repo with a HEAD. + git -C "$d" commit -q --allow-empty -m init +} + +# --- the happy path ------------------------------------------------------------ + +@test "clean rulesets and a non-git project: syncs all three paths" { + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] + [ "$(cat "$PROJ/.ai/protocols.org")" = "canonical protocols" ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "canonical startup" ] + [ "$(cat "$PROJ/.ai/scripts/helper")" = "canonical helper" ] +} + +@test "--delete removes a retired template file from the project" { + printf 'retired\n' > "$PROJ/.ai/workflows/gone.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] + [ ! -e "$PROJ/.ai/workflows/gone.org" ] +} + +@test "the scripts sync excludes python cache artifacts" { + mkdir -p "$RS/claude-templates/.ai/scripts/__pycache__" \ + "$RS/claude-templates/.ai/scripts/.pytest_cache" + printf 'junk\n' > "$RS/claude-templates/.ai/scripts/__pycache__/x.pyc" + printf 'junk\n' > "$RS/claude-templates/.ai/scripts/.pytest_cache/y" + printf 'junk\n' > "$RS/claude-templates/.ai/scripts/stray.pyc" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + # Assert the sync RAN before asserting what it didn't copy. Without this the + # absences below are satisfied by a skipped sync, and the whole test passes + # with every --exclude flag deleted from the script. + [[ "$output" == *"synced from templates"* ]] + [ -e "$PROJ/.ai/scripts/helper" ] + [ ! -e "$PROJ/.ai/scripts/__pycache__" ] + [ ! -e "$PROJ/.ai/scripts/.pytest_cache" ] + [ ! -e "$PROJ/.ai/scripts/stray.pyc" ] +} + +@test "project-owned directories are never touched by the sync" { + mkdir -p "$PROJ/.ai/project-workflows" "$PROJ/.ai/project-scripts" + printf 'mine\n' > "$PROJ/.ai/project-workflows/local.org" + printf 'mine\n' > "$PROJ/.ai/project-scripts/local.py" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] + [ "$(cat "$PROJ/.ai/project-workflows/local.org")" = "mine" ] + [ "$(cat "$PROJ/.ai/project-scripts/local.py")" = "mine" ] +} + +# --- guard one: rulesets dirty under the synced paths -------------------------- + +@test "a dirty file is withheld from the sync and named in the output" { + printf 'in-flight edit\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + printf 'stale\n' > "$PROJ/.ai/workflows/startup.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"withheld"* ]] + [[ "$output" == *"startup.org"* ]] + # The in-flight edit still must not land downstream. + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "stale" ] +} + +@test "ONE dirty file no longer blocks the other two rsyncs" { + # The 2026-07-30 incident, inverted. An edit to a workflow file used to + # withhold protocols.org and every script for every project; now it withholds + # only itself. + printf 'in-flight edit\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + printf 'stale protocols\n' > "$PROJ/.ai/protocols.org" + printf 'stale helper\n' > "$PROJ/.ai/scripts/helper" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ "$(cat "$PROJ/.ai/protocols.org")" = "canonical protocols" ] + [ "$(cat "$PROJ/.ai/scripts/helper")" = "canonical helper" ] +} + +@test "a dirty file's clean siblings under the SAME path still sync" { + printf 'canonical wrap\n' > "$RS/claude-templates/.ai/workflows/wrap.org" + git -C "$RS" add -A && git -C "$RS" commit -q -m 'add wrap' + printf 'in-flight edit\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + printf 'stale wrap\n' > "$PROJ/.ai/workflows/wrap.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + # The narrowing is per-file, not per-directory: only startup.org is held back. + [ "$(cat "$PROJ/.ai/workflows/wrap.org")" = "canonical wrap" ] +} + +@test "an excluded file is not deleted by --delete either" { + # rsync honors --exclude on both sides, so a withheld file that exists + # downstream must survive the run rather than being swept as a stray. + printf 'in-flight edit\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + printf 'project copy\n' > "$PROJ/.ai/workflows/startup.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ -e "$PROJ/.ai/workflows/startup.org" ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "project copy" ] +} + +@test "a dirty protocols.org withholds only itself; workflows and scripts sync" { + printf 'in-flight edit\n' >> "$RS/claude-templates/.ai/protocols.org" + printf 'stale protocols\n' > "$PROJ/.ai/protocols.org" + printf 'stale startup\n' > "$PROJ/.ai/workflows/startup.org" + printf 'stale helper\n' > "$PROJ/.ai/scripts/helper" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ "$(cat "$PROJ/.ai/protocols.org")" = "stale protocols" ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "canonical startup" ] + [ "$(cat "$PROJ/.ai/scripts/helper")" = "canonical helper" ] +} + +@test "dirty files across two synced paths withhold both, sync the third" { + printf 'in-flight\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + printf 'in-flight\n' >> "$RS/claude-templates/.ai/scripts/helper" + printf 'stale startup\n' > "$PROJ/.ai/workflows/startup.org" + printf 'stale helper\n' > "$PROJ/.ai/scripts/helper" + printf 'stale protocols\n' > "$PROJ/.ai/protocols.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "stale startup" ] + [ "$(cat "$PROJ/.ai/scripts/helper")" = "stale helper" ] + [ "$(cat "$PROJ/.ai/protocols.org")" = "canonical protocols" ] +} + +@test "an untracked file under a synced path is withheld, not blocking" { + printf 'new template\n' > "$RS/claude-templates/.ai/workflows/brand-new.org" + printf 'stale protocols\n' > "$PROJ/.ai/protocols.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"withheld"* ]] + # An unfinished new template must not ship half-written... + [ ! -e "$PROJ/.ai/workflows/brand-new.org" ] + # ...and must not hold back everything else. + [ "$(cat "$PROJ/.ai/protocols.org")" = "canonical protocols" ] +} + +@test "an untracked DIRECTORY under a synced path is withheld whole" { + # git collapses an untracked dir to one porcelain line with a trailing slash + # ("?? .../plugins/"), so the exclude has to match the directory rather than + # the files inside it. A half-written plugin dir must not ship. + mkdir -p "$RS/claude-templates/.ai/workflows/plugins" + printf 'half written\n' > "$RS/claude-templates/.ai/workflows/plugins/new.org" + printf 'stale protocols\n' > "$PROJ/.ai/protocols.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ ! -e "$PROJ/.ai/workflows/plugins" ] + [ "$(cat "$PROJ/.ai/protocols.org")" = "canonical protocols" ] +} + +@test "a file dirty in the index (staged, uncommitted) is withheld too" { + printf 'staged edit\n' >> "$RS/claude-templates/.ai/workflows/startup.org" + git -C "$RS" add claude-templates/.ai/workflows/startup.org + printf 'stale\n' > "$PROJ/.ai/workflows/startup.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "stale" ] +} + +@test "a renamed template withholds both the old and the new path" { + git -C "$RS" mv claude-templates/.ai/workflows/startup.org \ + claude-templates/.ai/workflows/renamed.org + printf 'stale startup\n' > "$PROJ/.ai/workflows/startup.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + # The new name must not ship mid-rename, and the old copy must not be swept + # while the rename is still uncommitted. + [ ! -e "$PROJ/.ai/workflows/renamed.org" ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "stale startup" ] +} + +@test "rulesets dirt OUTSIDE the synced paths does not block the sync" { + printf 'scratch\n' > "$RS/scratch.txt" + printf 'edit\n' >> "$RS/claude-templates/bin-ish.txt" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] +} + +# --- guard two: the project branch is behind its upstream ---------------------- + +@test "a project behind its upstream skips the sync" { + _mk_repo "$PROJ" + git init -q --bare "$WORK/remote" + git -C "$PROJ" remote add origin "$WORK/remote" + git -C "$PROJ" push -q -u origin HEAD + git -C "$PROJ" commit -q --allow-empty -m ahead + git -C "$PROJ" push -q origin HEAD + git -C "$PROJ" reset -q --hard HEAD~1 + printf 'stale\n' > "$PROJ/.ai/workflows/startup.org" + + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"behind upstream"* ]] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "stale" ] +} + +@test "a project AHEAD of its upstream still syncs" { + _mk_repo "$PROJ" + git init -q --bare "$WORK/remote" + git -C "$PROJ" remote add origin "$WORK/remote" + git -C "$PROJ" push -q -u origin HEAD + git -C "$PROJ" commit -q --allow-empty -m ahead + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] +} + +@test "a git project with no upstream syncs (rev-list fails, guard stays off)" { + _mk_repo "$PROJ" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] +} + +# --- edges --------------------------------------------------------------------- + +@test "a nonexistent project directory reports and exits 0 without syncing" { + run bash "$SYNC" "$WORK/does-not-exist" + [ "$status" -eq 0 ] + [[ "$output" == *"cannot enter"* ]] + [[ "$output" != *"synced from templates"* ]] + [ ! -e "$WORK/does-not-exist" ] +} + +@test "the sync is idempotent — a second run changes nothing" { + bash "$SYNC" "$PROJ" + first="$(find "$PROJ/.ai" -type f -exec sha256sum {} + | sort)" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] + second="$(find "$PROJ/.ai" -type f -exec sha256sum {} + | sort)" + [ "$first" = "$second" ] +} + +@test "a missing canonical source still reports success — the false-success path" { + # Faithfully inherited from the inline block, and pinned here because the + # manifest step depends on it: a last-synced record written after this + # branch would stamp a successful sync onto one where all three rsyncs + # failed. The guard work has to fix this before it can trust the record. + # Point at a rulesets that isn't there at all, rather than deleting the + # canonical subtree inside a live repo — that would show up as staged + # deletions and trip guard one, which is a different path entirely. + SYNC_RULESETS_DIR="$WORK/no-such-rulesets" run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"synced from templates"* ]] + # Nothing arrived, and the success line says otherwise. Asserted against a + # file that DOES arrive on a real sync — protocols.org is absent before any + # sync too, so its absence alone would prove nothing. + [ ! -e "$PROJ/.ai/scripts/helper" ] +} + +@test "a locally-edited template is silently overwritten, with no record kept" { + # Work's 2026-07-30 regression, pinned: a project patches a rulesets-owned + # file, the next sync reverts it to canonical, and nothing anywhere says so. + # The output is indistinguishable from an ordinary successful sync. + bash "$SYNC" "$PROJ" + printf 'local fix for a real bug\n' > "$PROJ/.ai/workflows/startup.org" + run bash "$SYNC" "$PROJ" + [ "$status" -eq 0 ] + [ "$(cat "$PROJ/.ai/workflows/startup.org")" = "canonical startup" ] + [[ "$output" == *"synced from templates"* ]] + # No warning, no backup, no manifest — the loss leaves no trace at all. + [[ "$output" != *"overwrote"* ]] + [[ "$output" != *"local edit"* ]] + [ ! -d "$PROJ/.ai/.sync-backups" ] +} diff --git a/claude-templates/.ai/scripts/tests/test-todo-cleanup.el b/claude-templates/.ai/scripts/tests/test-todo-cleanup.el index a92d238..1e964b3 100644 --- a/claude-templates/.ai/scripts/tests/test-todo-cleanup.el +++ b/claude-templates/.ai/scripts/tests/test-todo-cleanup.el @@ -1086,7 +1086,7 @@ line) is left untouched — the strip stops at the first non-planning line." ;; ;; todo-cleanup rewrites todo.org in place and left no copy behind, while both ;; sibling org-mutators back up to /tmp first. It is also the one that runs most -;; often (every wrap, every sentry fire). Emacs's own backup does not fire under +;; often (every wrap, every sentry cycle). Emacs's own backup does not fire under ;; --batch -q, so there was genuinely no undo short of git. (ert-deftest tc-backup-written-before-a-real-mutation () diff --git a/claude-templates/.ai/scripts/todo-cleanup.el b/claude-templates/.ai/scripts/todo-cleanup.el index cb333e2..516e9b1 100644 --- a/claude-templates/.ai/scripts/todo-cleanup.el +++ b/claude-templates/.ai/scripts/todo-cleanup.el @@ -843,7 +843,7 @@ event-log entry, pulling the timestamp from its CLOSED cookie. Honors Matches `lint-org.el' and `wrap-org-table.el', the other tools that rewrite these org files. todo-cleanup runs the most often of the three (every wrap, -every sentry fire), and Emacs's own backup does not fire under --batch -q, so +every sentry cycle), and Emacs's own backup does not fire under --batch -q, so without this a mechanical rewrite has no undo short of git — which recovers only to the last commit and loses intra-session work." (let* ((base (format "%s%s.before-todo-cleanup.%s" diff --git a/claude-templates/.ai/workflows/code-quality.org b/claude-templates/.ai/workflows/code-quality.org index 0481166..3c4ed8f 100644 --- a/claude-templates/.ai/workflows/code-quality.org +++ b/claude-templates/.ai/workflows/code-quality.org @@ -12,7 +12,7 @@ workflow only sequences them and collects the residue. *Behavior-preserving rests on a test net.* The passes below claim to preserve behavior, but a refactor on untested code is a guess, not a preservation. Where the scope has no tests, bring it under a characterization net first -(Normal/Boundary/Error per unit, per =testing.md='s "Adding Tests to Existing +(Normal/Boundary/Error per unit, per the =testing-standards= skill's "Adding Tests to Existing Untested Code") — that net is what turns "behavior-preserving" from an assertion into something the green suite actually verifies across each pass. diff --git a/claude-templates/.ai/workflows/daily-prep.org b/claude-templates/.ai/workflows/daily-prep.org index 3f21214..9f706d1 100644 --- a/claude-templates/.ai/workflows/daily-prep.org +++ b/claude-templates/.ai/workflows/daily-prep.org @@ -130,12 +130,33 @@ Morning Prep is where Craig reads the prep doc, mentally walks the schedule, and The Yesterday / Today / Blockers brief nests *directly under the standup meeting it's reported in* — never in a separate section. Plain section labels, no parenthetical questions in the rendered doc. -- *Blockers is always present.* When there are none, write =Blockers: None= explicitly — silence is ambiguous. +*The brief is a script, not a topic list.* The lines under each label are the words Craig says — complete first-person spoken sentences. Not fragments, not noun phrases, not a "bring these up" list. A topic list makes him compose the sentence live from a cue he wrote the night before and has since forgotten the shape of; a script is readable as-is. "Brief" invites bullets and bullets decay into topics, which is exactly the failure this rule exists to prevent. + +The script is a *draft for Craig to edit at the Phase 8 gate*, never words put in his mouth. That cuts both ways: a topic list forces him to compose and so fails safe, while a wrong script reads fluently enough to be spoken unchanged. So it gets the same gate scrutiny as the priorities. + +- *Blockers is always present.* A real blocker is stated as a full sentence, not a noun phrase. When there are none, write =Blockers: None= explicitly — silence is ambiguous. - *Outcomes, not attendance.* Never "met with <person>" — instead what came out of it: "<person> finished the branch CI/CD work." Never "went to the managers' meeting" — instead the development from it that affects this audience. - *No recurring 1:1s or ceremonies* in briefs — they're not news. - *Match the standup's altitude.* An engineering standup gets engineering-goal material only: what moved the platform or the demo forward — architecture docs, PRs, tracker tickets, partner meetings with use-case implications, integration discussions, security findings, dataset discoveries. It does NOT get: 1:1s, attending other standups, personal-tooling maintenance, profile updates, sending messages or email, meeting prep, booking travel, or interviews with non-engineering candidates. The three questions are really: (a) how have I moved us closer to the engineering goals, (b) what will I work on that moves us closer, (c) what information do I have that might impact the team or its goals. - A business-level (general) standup is different: features finished that leadership wanted, vacation/travel that affects availability or velocity, conference learnings, partner/customer decisions, cross-functional confusion worth clearing up. *Exclude routine maintenance and operational items — PR reviews don't belong here.* Foundational or strategic engineering work does; operations don't. +Worked contrast — the same day's material, written both ways: + +#+begin_example +Topics (the failure mode — a cue list, not a brief): + Bring: the freeze status, since Monday-or-later is the current answer. + The blocked review. The access request. + +Script (what belongs in the doc): + Yesterday: I fixed the bug where the selected region stayed editable + after an edit, and that's up for review along with the dependency + migration. + Today: I'm holding merges to development until the demo actually + happens, which now looks like Monday or later. + Blockers: None — the access request I raised Monday sits with the + platform team now, so it's slowing them rather than me. +#+end_example + (Drafting rules — first-person, deadline precision, recurring-meeting filters, the team-visible test — are in Phase 6.) *** Meetings @@ -315,7 +336,9 @@ Combine session history + the sweep + Day's Priorities + WAITING items into Yest - *Today*: 2-3 items max, from Day's Priorities. Include non-recurring meetings regardless of response status. - *Blockers*: the bar is "did this actually stop me from making progress?" — not "is someone else involved?" Default to under-reporting; Craig adds borderline items at the gate. FYIs come after blockers and stay loose. - *Team-visible filter*: only work that left Craig's local environment — pushed, shared, posted, changed in the tracker, or shifts what the team believes or plans. "If I didn't mention this, would someone make a worse decision or duplicate work?" If no, cut it. -- Readable aloud in under 60 seconds. +- *Write the words, not the topics.* Every line is a complete first-person sentence Craig can read aloud unchanged — see the worked contrast in the template's Standups section. No bare noun phrases, no "bring up X", and no identifier he wouldn't actually say out loud (a ticket key is fine where the team speaks in ticket keys, and wrong where they don't). +- Readable aloud in under 60 seconds — roughly 120-150 words across the three sections. Over budget means cut an item, not compress a sentence back into a fragment. +- *One script per standup.* Two standups on the same day get two separately-drafted scripts, because the altitude rules above admit different material to each. The same text under both headers is a defect, not a shortcut. *** Step 3: Capture learnings @@ -331,6 +354,8 @@ Also assemble the end-of-day block's upcoming-deadlines list: =DEADLINE:= entrie Present the assembled doc and ask whether Craig agrees with the Day's Priorities. If not, work with him to add / remove / substitute priorities and blocks until he confirms. Surface here, in one pass: meeting-goal questions, decline candidates, look-ahead flags, carry-forward decisions, and proposed schedule adjustments. +*Standup-script check (blocking).* The prep is not complete until every standup on that day's calendar carries its own script under its header, in the Phase 6 shape — spoken sentences, =Blockers:= present, altitude-matched. Check each standup individually and present the scripts at this gate for Craig to edit. Vacuous on a day with no standup, which is the common case in projects that hold none. This check exists because Phase 6's prose alone did not hold: on 2026-07-31 a prep wrote topic lists under both standup headers while every rule requiring a script was already on the page. Adding more prose to Phase 6 would not have caught that — the prose is what got skipped, so the requirement has to sit on a gate that blocks. + If the gate produces substantive rework, say so plainly: that's a =todo.org= staleness signal — the file should make Craig's current priorities obvious. Offer a task review. Update mode replaces the gate with a delta summary: what changed and why. @@ -448,3 +473,6 @@ The prep doc is born in =daily-prep/YYYY-MM-DD-daily-prep.org= and never moves; *** 2026-06-11: Full template rewrite — strict three-section doc, two run modes, mandatory priorities gate From Craig's instructive template spec (written 2026-06-10 evening, after reviewing generated preps) plus four refinements from his review of the first new-format prep. The doc is now exactly =* Heads-Up= / =* Day's Priorities= / =* Meetings / Focus Blocks=. Retired: the separate =* Standup Briefs= and =* Upcoming Deadlines= sections (briefs nest under their standup meeting; deadlines live in the end-of-day block), the =* [Day]'s Anchor Tasks= handoff (carry-forward lands directly in the next day's priorities, which are being built in the same sitting), the thin-link convention (entries mirror their todo.org task's heading and carry their own context — links in the body, never the heading), and standup-only mode (a brief refresh is an Update-mode run). New: two run modes (Create, with a MANDATORY end-of-flow priorities review gate whose disagreement signals todo.org staleness; Update, for when the world moves) both preceded by a triage-intake freshness check (no run in the last hour → run one first); event headers are the exact calendar title with ALL content nested under the event; per-event-type content rules (Morning Prep conflict-resolution strategy with drafts pre-written in the doc ready to send, standup altitude matching with =Blockers: None= explicit and operations excluded from business-level briefs, meetings carrying contribute/get/likely-questions with day-before prep blocks for "I don't know" answers and prep docs always =file:=-linked — the lesson of a prep that existed but couldn't be found in the minutes before a meeting that mattered, focus blocks as linked menus created day-before and marked free, lunch floor, the end-of-day "What Kind of Day Has It Been?" block carrying the deadlines list and generating tomorrow's prep); the look-ahead renders one day per line (=Fri 12:= …) with clear days marked =clear=; a requested-metrics Heads-Up slot rendered only when a metric is active (none yet); meetings verified against the live calendar at build and update time. + +*** 2026-07-31: Standup briefs are verbatim scripts, enforced at the Phase 8 gate +A prep wrote =Bring:= topic lists under both standup headers while every rule requiring a Yesterday/Today/Blockers brief was already on the page. The rule existed and was skipped, so the fix is a gate rather than more prose: Phase 8 now blocks until every standup on the day's calendar carries its own script, and the Standups section says plainly that the lines are the words Craig speaks — complete first-person sentences, one script per standup since the altitude rules admit different material to each, roughly 120-150 words for the under-60-seconds target. A worked topics-vs-script contrast sits with the shape rules, because prose decays back into bullets and an example doesn't. The script is a draft Craig edits at the gate, never words put in his mouth: a topic list fails safe by forcing him to compose, where a wrong script reads fluently enough to be spoken unchanged. diff --git a/claude-templates/.ai/workflows/helper-mode.org b/claude-templates/.ai/workflows/helper-mode.org index a6acfa7..b32d574 100644 --- a/claude-templates/.ai/workflows/helper-mode.org +++ b/claude-templates/.ai/workflows/helper-mode.org @@ -12,13 +12,14 @@ The governing fact behind every rule below: the session-context split isolates e * When to Use This Workflow -No operator trigger phrase. A helper reaches this contract one of three ways: +No operator trigger phrase. A helper reaches this contract one of two ways: - The =ai --helper= launcher routes here after the roster confirms a live agent (the deterministic path). -- Startup's roster check finds the session is not alone and routes here instead of running normal startup (the safety net for a raw =claude= launch). - An explicit "you are a helper, follow helper-mode.org" instruction (the manual fallback). -If none of those applies — the roster shows the session is alone — this is a primary session. Run normal [[file:startup.org][startup.org]], not this. +There is deliberately no third way, and the gap matters: *startup does not check the roster*. A bare =claude= launched into a project that already has a live session runs full primary startup — pulls, rsync, inbox processing — without ever reaching this file. That safety net is designed (see Status below) but unbuilt, so nothing catches a raw launch. Use =ai --helper=. + +If neither route applies, this is a primary session. Run normal [[file:startup.org][startup.org]], not this. * Identity @@ -92,10 +93,28 @@ A helper does not run normal startup. It runs a light version: When the helper's work is done: -1. Re-run the roster (=.ai/scripts/agent-roster=) to learn whether a primary is still live. +1. Re-run the roster to learn whether a primary is still live. Pass the project root explicitly — =agent-roster= defaults to =$PWD= and keeps only agents at or inside that root, so calling it from a subdirectory hides a primary sitting at the root and reports "alone": + + #+begin_src bash + root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" + if [ -x "$root/.ai/scripts/agent-roster" ]; then + "$root/.ai/scripts/agent-roster" "$root"; rc=$? + else + rc=2 + fi + echo "roster rc=$rc" + #+end_src + + Read rc as =wrap-it-up.org= Step 0 does: 1 means a primary is still live, 0 means this helper is orphaned, and 2 (or an absent script) means unavailable — which takes the same archive-only path as 1, because leaving work uncommitted is recoverable and committing under a live primary is not. 2. *Primary still live (the normal case):* finalize the Summary in the helper's own =.ai/session-context.d/<id>.org=, archive it to =.ai/sessions/YYYY-MM-DD-HH-MM-<id>-<description>.org=, and stop. Do NOT commit, push, or run hygiene — the primary's next commit picks up the archived file and any scoped edits the helper left in the tree. 3. *Orphaned helper (roster shows the helper is now alone):* the primary already exited, so the helper assumes full closing duties — the git ban lifts because the concurrency that justified it is gone. Commit and push the tree (including the helper's own edits, which would otherwise strand as a dirty tree), per the normal wrap-up flow in [[file:wrap-it-up.org][wrap-it-up.org]]. * Status -Phase 1.5 of the generic-agent-runtime spec. This contract is the canonical home; the spawn paths (=ai --helper=, startup's roster branch) and the [[file:wrap-it-up.org][wrap-it-up.org]] helper branch route here. Those wiring pieces ship behind the spec's bats-then-drills-then-pilot gate and are not yet live; until then, the manual "you are a helper" instruction is how a session adopts this contract. +Phase 1.5 of the generic-agent-runtime spec. This contract is the canonical home; the spawn paths and the [[file:wrap-it-up.org][wrap-it-up.org]] helper branch route here. + +Live now: =ai --helper <project>= (roster check, id assignment, helper opener, its own tmux window), the explicit "you are a helper" instruction, and the wrap-it-up.org Step 0 helper branch. + +Not built yet, and worth knowing because it is the gap you can fall into: *startup has no roster check*. A second session launched as a bare =claude= in a project that already has one runs full primary startup — pulls, rsync, inbox processing — with no idea another agent is live. Until that safety net exists, =ai --helper= is not merely the preferred path, it is the only one that makes a helper without being told. + +Also unbuilt: the live-helper gate that pauses a primary's file-wide hygiene passes (=todo-cleanup.el=, =lint-org.el=, =wrap-org-table.el=) while a helper is mid-edit. Data-integrity rule 1 above describes the intended behavior; nothing enforces it yet, so a primary running hygiene can still clobber a helper's just-written scoped edit. diff --git a/claude-templates/.ai/workflows/no-approvals.org b/claude-templates/.ai/workflows/no-approvals.org index b4c7fcf..6b5c7fa 100644 --- a/claude-templates/.ai/workflows/no-approvals.org +++ b/claude-templates/.ai/workflows/no-approvals.org @@ -46,7 +46,7 @@ The interaction gates that step the workflow back to Craig for an "OK to proceed The engineering-discipline gates protect quality, not Craig's interaction time. They remain in force: -- =/review-code= against the staged diff before every commit. Critical and Important findings still block. Minor findings still surface. No "proceed anyway" override unless Craig has given it explicitly for this batch. +- =/review-code= against the staged diff before every commit, dispatched as an isolated adversarial reviewer per the =publish= skill's Step 1 — no-approvals removes *interaction* gates, never the isolation. Critical and Important findings still block, and the re-review loop still runs to approval. Minor findings still surface. No "proceed anyway" override unless Craig has given it explicitly for this batch. If the review can't reach approval — three rounds, a recurring finding, or a =Needs Discussion= verdict — that is a genuine question: park the item per step 4 and move to the next one rather than committing past a standing finding. - =/voice personal= on every publish artifact (commit messages, PR titles + bodies, PR review comments). The full pattern walk happens. The printed result just doesn't wait for approval. - The full test suite + lint + compile before commit (per =verification.md=). - Fetch-and-reconcile in the =publish= skill, Step 0. @@ -70,7 +70,7 @@ For each item: - Do the work. - Update the Session Log per the rules in =protocols.org=. -- Before any commit: run =/review-code= against the staged diff. Surface Critical and Important findings inline; fix them and re-review until clean. Minor findings show but don't block. +- Before any commit: dispatch the isolated adversarial reviewer per the =publish= skill's Step 1 — never review your own staged diff inline. Surface Critical and Important findings; fix them and send the updated diff back to the *same* reviewer until it approves. Minor findings show but don't block and never earn another round. If the review can't reach approval — three rounds, a finding that recurs after being reported fixed, or a =Needs Discussion= verdict — park the item per step 4 with the standing findings and move on; don't commit past a blocking finding. - Draft the commit message. Run =/voice personal= (the skill, or walk the patterns inline if unavailable). Print the final message inline before committing so the log shows it. - Commit and push. - One-line status between items ("Task X done, on to Y.") so Craig knows what's happening when he checks back in. diff --git a/claude-templates/.ai/workflows/sentry.org b/claude-templates/.ai/workflows/sentry.org index e25ca39..b25fc14 100644 --- a/claude-templates/.ai/workflows/sentry.org +++ b/claude-templates/.ai/workflows/sentry.org @@ -4,11 +4,11 @@ * Overview -Sentry is an interval loop that keeps a project's hygiene current while Craig is away. Each fire walks a fixed list of passes — roam pull, inbox zero, triage (no mail or messengers), todo cleanup, task audit, working-files hygiene, spec board, link integrity, git health, prep freshness, bug and refactor finding, and (opt-in) solo-task implementation — and commits each pass's writing to a throwaway daily branch. Nothing pushes. In the morning Craig reviews the branch, squash-merges what he wants, and deletes it. +Sentry is an interval loop that keeps a project's hygiene current while Craig is away. Each cycle walks a fixed list of passes — roam pull, inbox zero, triage (no mail or messengers), todo cleanup, task audit, working-files hygiene, spec board, link integrity, git health, prep freshness, bug and refactor finding, and (opt-in) solo-task implementation — and commits each pass's writing to a throwaway daily branch. Nothing pushes. In the morning Craig reviews the branch, squash-merges what he wants, and deletes it. The design goal is a project that greets the morning already tidy, with every judgment call and every destructive action parked in an approval queue rather than executed unattended. Sentry does the mechanical sweeping; Craig does the deciding. -This file is the engine. It owns the entry gates, the branch mechanics, the lock model, the per-fire pass runner, the digest and approval queue, the skip semantics, and the stop-sentry shutdown. The =agent-lock= helper (=.ai/scripts/agent-lock=) provides the locks. The passes reuse existing workflows (=inbox.org=, =triage-intake.org=, =clean-todo.org=, =task-audit.org=) under sentry's unattended contract. +This file is the engine. It owns the entry gates, the branch mechanics, the lock model, the per-cycle pass runner, the digest and approval queue, the skip semantics, and the stop-sentry shutdown. The =agent-lock= helper (=.ai/scripts/agent-lock=) provides the locks. The passes reuse existing workflows (=inbox.org=, =triage-intake.org=, =clean-todo.org=, =task-audit.org=) under sentry's unattended contract. * When to Use This Workflow @@ -58,7 +58,7 @@ Craig types the sentry trigger, so the first moves run with him at the terminal. Wait for an answer. Sentry can't start unattended from a dirty state; that's the point. -3. *Green-suite gate.* Run the project's full suite (=make test=, or the project's equivalent — detect it). Read the output. If anything is red, describe the failures and offer to investigate before arming. The loop starts only on a green baseline, because every unattended fire measures itself against "did I break this?" and a pre-existing red poisons that check. +3. *Green-suite gate.* Run the project's full suite (=make test=, or the project's equivalent — detect it). Read the output. If anything is red, describe the failures and offer to investigate before arming. The loop starts only on a green baseline, because every unattended cycle measures itself against "did I break this?" and a pre-existing red poisons that check. 4. *Prior sentry branch.* =git branch --list 'sentry/*'=. An unmerged =sentry/*= branch from a previous night means the morning review didn't happen. Surface it and offer to squash-merge or delete it now (Craig is present); don't stack a second sentry branch on the first. @@ -75,53 +75,53 @@ Craig types the sentry trigger, so the first moves run with him at the terminal. The host suffix (=uname -n=) stops a same-date collision between the two daily drivers. The working tree now sits on this branch overnight — the launch hands the repo to sentry until the morning merge. Reclaiming it mid-night means stopping sentry first (see Stop Sentry). Note the Emacs buffer-revert caveat to Craig if he has the repo open: files change on disk under him overnight, so buffers want reverting after the morning merge (see =emacs.md=). -7. *Arm the loop.* Start =/loop= at the interval (default hourly; Craig's "every <interval>" phrase overrides) with the per-fire body being one sentry fire (the Pass Runner below). Confirm the arming in one line: interval, branch name, project. +7. *Arm the loop.* Start =/loop= at the interval (default hourly; Craig's "every <interval>" phrase overrides) with the per-cycle body being one sentry cycle (the Pass Runner below). Confirm the arming in one line: interval, branch name, project. * The lock model Two locks, both served by =.ai/scripts/agent-lock= (names only; the helper owns the paths, which live on tmpfs under =$XDG_RUNTIME_DIR/agent-locks/=, host-local and cleared on reboot). -*Single-runner lock* (=sentry-<project>=, where =<project>= is the repo-root basename: =basename "$(git rev-parse --show-toplevel)"= — the same derivation =wrap-it-up.org='s guard uses, so the two agree on the lock name). Each fire acquires it at fire start and releases it at fire end, and refreshes it between passes (the heartbeat, so a live fire's lock never ages past one pass). If =/loop= fires again while a previous fire still holds it, the new fire's acquire fails and the fire skips with one digest line — no two fires run at once. The bounded wait is short (a few seconds); a live fire means defer, not queue. +*Single-runner lock* (=sentry-<project>=, where =<project>= is the repo-root basename: =basename "$(git rev-parse --show-toplevel)"= — the same derivation =wrap-it-up.org='s guard uses, so the two agree on the lock name). Each cycle acquires it at cycle start and releases it at cycle end, and refreshes it between passes (the heartbeat, so a live cycle's lock never ages past one pass). If =/loop= fires again while a previous cycle still holds it, the new cycle's acquire fails and the cycle skips with one digest line — no two cycles run at once. The bounded wait is short (a few seconds); a live cycle means defer, not queue. *Roam-write lock* (=roam-write=). A pass that edits a file under =~/org/roam= acquires it, runs =capture-guard --wait= (the human-capture layer stays underneath), edits the working tree, triggers =systemctl --user start roam-sync.service=, and releases. The lock spans only edit-plus-trigger. Sentry never runs =git= against =~/org/roam= — roam-sync stays the repo's only committer (the 2026-06-24 one-git-owner rule). Pass 1's =pull --ff-only= is the sole, read-only exception. -Every reclaim of a stale lock surfaces in the digest — the helper prints the reclaim note, and the fire records it. A reclaim during a genuinely slow pass is possible, so it's never silent. +Every reclaim of a stale lock surfaces in the digest — the helper prints the reclaim note, and the cycle records it. A reclaim during a genuinely slow pass is possible, so it's never silent. * The Pass Runner — one contract per pass -Each fire, after acquiring the single-runner lock and verifying branch state (below), walks the pass list in order. Every pass follows the same four-step contract: +Each cycle, after acquiring the single-runner lock and verifying branch state (below), walks the pass list in order. Every pass follows the same four-step contract: 1. *Probe* — a cheap existence check for the pass's target (named per pass below). Absent → the pass is one skip line in the digest and nothing more. This is what makes the pass list portable: passes self-activate where their target exists and stay silent elsewhere, with zero per-project configuration. 2. *Work* — run the pass under the unattended contract. Quick, solo, already-agreed mechanical actions execute. Anything destructive or requiring judgment does *not* execute — it appends to the morning-approval queue (what, why, the exact command or edit that fires on approval). A pass runs fully or not at all; there is no reduced-form pass. -3. *Session-context entry* — a pass that does or queues work appends its digest line to the =session-context.org= Session Log (path resolved via =.ai/scripts/session-context-path=) before its commit, so a crash between them still leaves the trail. Per-pass lines for an all-quiet fire (every pass probe-skipped or no-op) are not written one by one — the fire collapses to a single heartbeat at fire-end (below), so an idle fire doesn't spray one skip line per pass. +3. *Session-context entry* — a pass that does or queues work appends its digest line to the =session-context.org= Session Log (path resolved via =.ai/scripts/session-context-path=) before its commit, so a crash between them still leaves the trail. Per-pass lines for an all-quiet cycle (every pass probe-skipped or no-op) are not written one by one — the cycle collapses to a single heartbeat at cycle-end (below), so an idle cycle doesn't spray one skip line per pass. 4. *Commit* — if the pass wrote to disk, commit it: =chore(sentry): <pass> — <what changed>=. One commit per writing pass. A probe-skip or a no-op pass writes nothing and commits nothing. Between passes, refresh the single-runner lock (=agent-lock refresh sentry-<project>=) — the heartbeat. -** Branch-state verification (fire start, before the passes) +** Branch-state verification (cycle start, before the passes) -After acquiring the lock, confirm the fire is safe to run: +After acquiring the lock, confirm the cycle is safe to run: -- *On the right branch* — HEAD is =sentry/<today>-<host>=. If the loop was armed on a prior day and crossed midnight, the branch keeps the arming date; that's fine, morning teardown handles it. If HEAD is somehow *not* a sentry branch (an interrupted stop, a manual checkout), skip the whole fire with a digest line rather than committing onto main. -- *Clean of foreign changes* — =git diff --quiet HEAD= excluding the spine set (=session-context.org= / =session-context.d/=, resolved via =session-context-path=). Sentry's own spine writes must not trip this; a genuinely unexpected dirty tree (something outside the spine changed and wasn't committed by a prior pass) poisons the fire — skip it with a digest line, the next fire retries. +- *On the right branch* — HEAD is =sentry/<today>-<host>=. If the loop was armed on a prior day and crossed midnight, the branch keeps the arming date; that's fine, morning teardown handles it. If HEAD is somehow *not* a sentry branch (an interrupted stop, a manual checkout), skip the whole cycle with a digest line rather than committing onto main. +- *Clean of foreign changes* — =git diff --quiet HEAD= excluding the spine set (=session-context.org= / =session-context.d/=, resolved via =session-context-path=). Sentry's own spine writes must not trip this; a genuinely unexpected dirty tree (something outside the spine changed and wasn't committed by a prior pass) poisons the cycle — skip it with a digest line, the next cycle retries. * Unattended safety — skip, never degrade -With no one at the terminal, any unsafe state makes the affected scope skip with one digest line, and the next fire retries. Unsafe states and their scope: +With no one at the terminal, any unsafe state makes the affected scope skip with one digest line, and the next cycle retries. Unsafe states and their scope: -- *Unexpected dirty tree* (non-spine) → skip the whole fire. -- *Lost or un-acquirable single-runner lock* → skip the fire (another fire holds it, or the helper is missing). +- *Unexpected dirty tree* (non-spine) → skip the whole cycle. +- *Lost or un-acquirable single-runner lock* → skip the cycle (another cycle holds it, or the helper is missing). - *A pass's own precondition unmet* (its probe fails, or a dependency is dirty) → skip that pass only. -- *Red suite at fire-end* (see below) → the commits stay on the branch, flagged in the digest for morning review; the fire doesn't roll back. +- *Red suite at cycle-end* (see below) → the commits stay on the branch, flagged in the digest for morning review; the cycle doesn't roll back. -Skips are never silent and never partial. Inside a *working* fire, a pass line means the pass fully ran and a skip line names why it didn't. An *all-quiet* fire is not a silent skip either: its single =sentry at HH:MM: nothing= heartbeat is the explicit record that every pass found nothing, standing in for a wall of identical skip lines. The anti-silence rule targets a pass that hides work it should have surfaced; a quiet fire has surfaced that there was none. +Skips are never silent and never partial. Inside a *working* cycle, a pass line means the pass fully ran and a skip line names why it didn't. An *all-quiet* cycle is not a silent skip either: its single =sentry at HH:MM: nothing= heartbeat is the explicit record that every pass found nothing, standing in for a wall of identical skip lines. The anti-silence rule targets a pass that hides work it should have surfaced; a quiet cycle has surfaced that there was none. ** Multi-day stall notification -An unmerged prior =sentry/*= branch at fire start (the morning review never happened) skips the fire. After the *second consecutive* fire skipped for this reason, send one persistent desktop notification naming the project and branch: +An unmerged prior =sentry/*= branch at cycle start (the morning review never happened) skips the cycle. After the *second consecutive* cycle skipped for this reason, send one persistent desktop notification naming the project and branch: : sentry stalled: <branch> unmerged — merge or delete to resume @@ -135,11 +135,11 @@ In order. Each names its detection probe. A pass whose probe fails is one skip l 2. *Inbox zero* — run =inbox.org= roam mode under the no-approvals contract: quick+solo+agreed items execute, shared-asset and convention proposals park (prepared diff, =VERIFY= task, sender reply) in the approval queue. Edits to =~/org/roam/inbox.org= take the roam-write lock + =capture-guard=. Probe: the roam clone or a project =inbox/= exists. Tidying the shared roam inbox is allowed from *any* project session, work included — it's housekeeping on a shared resource, not a durable KB-node write, so the work-denylist doesn't gate it (=knowledge-base.md=). Never park it as a cross-project boundary crossing. -3. *Triage intake — mail and messenger sources excluded.* Run =triage-intake.org=, loading only its non-mail, non-messenger source plugins (calendar, PR/ticketing). The mail and messenger plugins — cmail, any Gmail variant, Telegram, Signal, chat DMs — are never loaded by a sentry fire: Craig ruled 2026-07-21 that sentry doesn't check email or messengers. A manual "triage intake" still scans everything. Probe: the project has at least one *active* triage source that survives that exclusion — a project-specific plugin (=.ai/project-workflows/triage-intake.*.org=), or a non-empty =:TRIAGE_SOURCES:= declaration naming general plugins that exist. Mere presence of the template-synced general plugins does *not* activate the pass; a project that declares no sources, or whose only declared sources are mail or messengers, probe-skips (see =docs/specs/2026-07-20-triage-source-activation-spec.org=). Destructive actions (deleting, archiving, sending) queue; they never fire unattended. +3. *Triage intake — mail and messenger sources excluded.* Run =triage-intake.org=, loading only its non-mail, non-messenger source plugins (calendar, PR/ticketing). The mail and messenger plugins — cmail, any Gmail variant, Telegram, Signal, chat DMs — are never loaded by a sentry cycle: Craig ruled 2026-07-21 that sentry doesn't check email or messengers. A manual "triage intake" still scans everything. Probe: the project has at least one *active* triage source that survives that exclusion — a project-specific plugin (=.ai/project-workflows/triage-intake.*.org=), or a non-empty =:TRIAGE_SOURCES:= declaration naming general plugins that exist. Mere presence of the template-synced general plugins does *not* activate the pass; a project that declares no sources, or whose only declared sources are mail or messengers, probe-skips (see =docs/specs/2026-07-20-triage-source-activation-spec.org=). Destructive actions (deleting, archiving, sending) queue; they never cycle unattended. -4. *Todo cleanup* — the =clean-todo.org= mechanics (hygiene pass + =--archive-done= + =--convert-subtasks=). Probe: a root =todo.org=. Note that =--archive-done= is not purely an org-file pass on its first run in a project: it creates =archive/task-archive.org= and appends a =.gitignore= entry, so it produces a real tracked-file commit and correctly trips the fire-end conditional suite. (archangel, first live run 2026-07-21.) +4. *Todo cleanup* — the =clean-todo.org= mechanics (hygiene pass + =--archive-done= + =--convert-subtasks=). Probe: a root =todo.org=. Note that =--archive-done= is not purely an org-file pass on its first run in a project: it creates =archive/task-archive.org= and appends a =.gitignore= entry, so it produces a real tracked-file commit and correctly trips the cycle-end conditional suite. (archangel, first live run 2026-07-21.) -5. *Task audit* — the *mechanical subset* of =task-audit.org= hourly (staleness counts, structural checks, cookie recomputation); the judgment half (priority regrades, consolidations, merge candidates) runs *once per night* and queues its findings rather than repeating them every fire. Probe: a root =todo.org=. A full audit every hour is too heavy and re-surfaces the same judgment calls all night. (takuzu, first live run 2026-07-21.) Factual staleness fixes that are unambiguous still execute. +5. *Task audit* — the *mechanical subset* of =task-audit.org= hourly (staleness counts, structural checks, cookie recomputation); the judgment half (priority regrades, consolidations, merge candidates) runs *once per night* and queues its findings rather than repeating them every cycle. Probe: a root =todo.org=. A full audit every hour is too heavy and re-surfaces the same judgment calls all night. (takuzu, first live run 2026-07-21.) Factual staleness fixes that are unambiguous still execute. 6. *Working-files hygiene* — flag =working/<slug>/= directories whose backing task is closed (a filing candidate per =working-files.md=). Probe: a =working/= directory exists. The filing itself queues (it's a judgment move). @@ -151,25 +151,25 @@ In order. Each names its detection probe. A pass whose probe fails is one skip l 10. *Prep + symlink freshness* — stale daily-prep docs, broken symlinks. Probe: the prep dir / symlinks exist (work and home only, in practice). -11. *Bug and refactor finding* — hunt for real bugs and worthwhile refactoring opportunities in the project's codebase: static analysis (=shellcheck= for shell, the project's own linters for its languages), config sanity checks, plus one targeted code-reading area per fire. Rotate the area across fires and name it in the digest, so coverage accumulates over a night instead of re-reading the same corner. Randomized property sweeps (generate-and-verify against an engine's own invariants) are good quiet-fire work here, reaching past a frozen test corpus. Expect the pass to go honestly quiet after the first few fires find the standing defects; a quiet hunt is a result, not a failure. (takuzu, first live run 2026-07-21: three real fixes in the first four fires, then quiet.) This pass does *not* run the test suite — the entry baseline already ran it, and re-running it hourly is anti-pattern 5; read the entry result instead. Probe: the project carries a codebase — source under version control beyond its org and tooling files. File each verified bug as a graded task in =todo.org= per the severity × frequency matrix (=todo-format.md=), and each refactoring opportunity as a =:refactor:= task, deduped against existing tasks; an unverifiable suspicion is a digest line, not a task. *Find, never fix in this pass* — the finding files a task and stops. A fix happens only in the opt-in implementation pass below, and only after the finding is a filed task that pass then re-verifies from scratch (see the premise rule there). A freshly-found "bug" can be a misread — one was filed and retracted two fires apart on 2026-07-23 — so the file-then-verify-then-fix pipeline is deliberate: the task is the checkpoint, not a same-breath fix. (Added at Craig's order 2026-07-21, first dogfooded in dotfiles; refactor-finding added 2026-07-24.) +11. *Bug and refactor finding* — hunt for real bugs and worthwhile refactoring opportunities in the project's codebase: static analysis (=shellcheck= for shell, the project's own linters for its languages), config sanity checks, plus one targeted code-reading area per cycle. Rotate the area across cycles and name it in the digest, so coverage accumulates over a night instead of re-reading the same corner. Randomized property sweeps (generate-and-verify against an engine's own invariants) are good quiet-cycle work here, reaching past a frozen test corpus. Expect the pass to go honestly quiet after the first few cycles find the standing defects; a quiet hunt is a result, not a failure. (takuzu, first live run 2026-07-21: three real fixes in the first four cycles, then quiet.) This pass does *not* run the test suite — the entry baseline already ran it, and re-running it hourly is anti-pattern 5; read the entry result instead. Probe: the project carries a codebase — source under version control beyond its org and tooling files. File each verified bug as a graded task in =todo.org= per the severity × frequency matrix (=todo-format.md=), and each refactoring opportunity as a =:refactor:= task, deduped against existing tasks; an unverifiable suspicion is a digest line, not a task. *Find, never fix in this pass* — the finding files a task and stops. A fix happens only in the opt-in implementation pass below, and only after the finding is a filed task that pass then re-verifies from scratch (see the premise rule there). A freshly-found "bug" can be a misread — one was filed and retracted two cycles apart on 2026-07-23 — so the file-then-verify-then-fix pipeline is deliberate: the task is the checkpoint, not a same-breath fix. (Added at Craig's order 2026-07-21, first dogfooded in dotfiles; refactor-finding added 2026-07-24.) -12. *Solo-task implementation (opt-in — =:SENTRY_MAY_IMPLEMENT:=)* — work the backlog's solo, decision-free tasks on the branch. Probe: =.ai/notes.org= Workflow State carries =:SENTRY_MAY_IMPLEMENT: yes= *and* the project holds =:COMMIT_AUTONOMY:= (the implement pass commits). Absent the marker, skip — this pass is off by default, because it turns the morning from a two-minute merge into a code review, and that's the project owner's call. When on: invoke =work-the-backlog.org= under its unattended-loop contract (no pre-flight Q&A — there's no Craig overnight), eligibility =TODO= + =:solo:=, with the defer checklist deciding act-vs-file. The overnight-only tightening: only the *ready* bucket implements (clears every checklist item with zero open decisions); a task needing even one quick decision defers to a =VERIFY= rather than guessing, exactly as the loop caller already does. Commit each logical change to the sentry branch; *never push* — the morning review and merge is the gate, same as every other pass. The full quality bar holds (TDD, suite green before each commit, =/review-code=, =/voice=), and =/review-code= here runs the *premise check first*: reproduce the bug or confirm the problem is real before judging the diff. The review is the fact-checker that a filed claim never got, and it is what makes fixing-on-a-branch safe (Craig, 2026-07-24). A task that fails its premise check is not implemented — the finding was wrong, and that outcome is a digest line, not a commit. (Added at Craig's direction 2026-07-24: overnight implement-on-branch, gated and never-pushed.) +12. *Solo-task implementation (opt-in — =:SENTRY_MAY_IMPLEMENT:=)* — work the backlog's solo, decision-free tasks on the branch. Probe: =.ai/notes.org= Workflow State carries =:SENTRY_MAY_IMPLEMENT: yes= *and* the project holds =:COMMIT_AUTONOMY:= (the implement pass commits). Absent the marker, skip — this pass is off by default, because it turns the morning from a two-minute merge into a code review, and that's the project owner's call. When on: invoke =work-the-backlog.org= under its unattended-loop contract (no pre-flight Q&A — there's no Craig overnight), eligibility =TODO= + =:solo:=, with the defer checklist deciding act-vs-file. The overnight-only tightening: only the *ready* bucket implements (clears every checklist item with zero open decisions); a task needing even one quick decision defers to a =VERIFY= rather than guessing, exactly as the loop caller already does. Commit each logical change to the sentry branch; *never push* — the morning review and merge is the gate, same as every other pass. The full quality bar holds (TDD, suite green before each commit, the isolated adversarial review per =publish= Step 1 with its re-review loop, =/voice=), and the review here runs the *premise check first*: reproduce the bug or confirm the problem is real before judging the diff. The review is the fact-checker that a filed claim never got, and it is what makes fixing-on-a-branch safe (Craig, 2026-07-24). A task that fails its premise check is not implemented — the finding was wrong, and that outcome is a digest line, not a commit. A task whose review never reaches approval — three rounds, a recurring finding, or a =Needs Discussion= verdict — is the same shape: no commit, and a digest line naming the standing findings, so the morning review sees what the reviewer would not pass rather than finding the task silently absent. (Added at Craig's direction 2026-07-24: overnight implement-on-branch, gated and never-pushed.) (KB lesson promotion — the pass the original proposal listed eleventh — is deferred to vNext. An unattended judgment pass writing to the shared knowledge base waits until sentry has quiet weeks behind it and a designed detection heuristic. See the filed lesson-detection-heuristic task.) -* Fire-end — conditional suite, then the digest commit +* Cycle-end — conditional suite, then the digest commit After the passes: -1. *Conditional suite run.* If any pass this fire modified files *outside* the org/spine set (a code-touching pass, rare but possible via fixtures), run the full suite once. A green run confirms the fire's commits are safe; a red run flags the digest for morning review — the commits stay on the branch (nothing is pushed, so the morning gate catches it). No per-pass suite runs: the entry run is the green baseline, and hourly per-commit runs would turn a seconds-long fire into minutes all night. Fires that only touched org/spine files skip this. +1. *Conditional suite run.* If any pass this cycle modified files *outside* the org/spine set (a code-touching pass, rare but possible via fixtures), run the full suite once. A green run confirms the cycle's commits are safe; a red run flags the digest for morning review — the commits stay on the branch (nothing is pushed, so the morning gate catches it). No per-pass suite runs: the entry run is the green baseline, and hourly per-commit runs would turn a seconds-long cycle into minutes all night. Cycles that only touched org/spine files skip this. -2. *Heartbeat or digest, then commit.* Decide quiet vs working. A *quiet* fire — every pass probe-skipped or no-op, nothing added to the approval queue — writes a single heartbeat line to the Session Log, =sentry at HH:MM: nothing= (HH:MM local, from =date=), and no per-pass digest block. A *working* fire — any pass ran, wrote, or queued — writes its full per-pass digest block. Then commit any accumulated spine writes in one sweep: =chore(sentry): digest — <date> <time> fire= for a working fire, =chore(sentry): heartbeat — <date> <time>= for a quiet one, so even a quiet fire leaves a clean tree for the next branch-state check (where the spine is untracked, the mirror-only case, there is nothing to commit and the heartbeat line stays in the working-tree anchor). This is the silent-until-signal policy (see =docs/specs/2026-07-20-silent-until-signal-monitors-spec.org=): an all-quiet night collapses from a wall of no-op digests to a list of one-line heartbeats, while a fire that actually did or queued something still writes the full record. +2. *Heartbeat or digest, then commit.* Decide quiet vs working. A *quiet* cycle — every pass probe-skipped or no-op, nothing added to the approval queue — writes a single heartbeat line to the Session Log, =sentry at HH:MM: nothing= (HH:MM local, from =date=), and no per-pass digest block. A *working* cycle — any pass ran, wrote, or queued — writes its full per-pass digest block. Then commit any accumulated spine writes in one sweep: =chore(sentry): digest — <date> <time> cycle= for a working cycle, =chore(sentry): heartbeat — <date> <time>= for a quiet one, so even a quiet cycle leaves a clean tree for the next branch-state check (where the spine is untracked, the mirror-only case, there is nothing to commit and the heartbeat line stays in the working-tree anchor). This is the silent-until-signal policy (see =docs/specs/2026-07-20-silent-until-signal-monitors-spec.org=): an all-quiet night collapses from a wall of no-op digests to a list of one-line heartbeats, while a cycle that actually did or queued something still writes the full record. 3. *Release the single-runner lock.* * The digest and the approval queue -*Digest.* A *working* fire appends its block to the =session-context.org= Session Log (the spine the fire already writes), so it survives a crash, rides the session archive, and is on screen in the running session. One block per working fire: the timestamp, then one line per pass (ran + what, or skipped + why), plus any lock reclaim notes. A *quiet* fire (nothing done or queued) writes no block — just the one heartbeat line =sentry at HH:MM: nothing= (the silent-until-signal policy). The per-pass block is a working-fire artifact; it still carries one line per pass so a real skip inside a working fire is never hidden. +*Digest.* A *working* cycle appends its block to the =session-context.org= Session Log (the spine the cycle already writes), so it survives a crash, rides the session archive, and is on screen in the running session. One block per working cycle: the timestamp, then one line per pass (ran + what, or skipped + why), plus any lock reclaim notes. A *quiet* cycle (nothing done or queued) writes no block — just the one heartbeat line =sentry at HH:MM: nothing= (the silent-until-signal policy). The per-pass block is a working-cycle artifact; it still carries one line per pass so a real skip inside a working cycle is never hidden. *Approval queue.* Destructive and judgment actions accumulate under one heading in the same file — =* Sentry approval queue (<date>)= — newest last. Each item carries three things: *what* (the action), *why* (what triggered it), and the *exact command or edit* that fires on approval. The morning review is Craig reading this heading top to bottom and running or discarding each item. @@ -186,13 +186,13 @@ Sentry never merges its own branch. In the morning Craig: A bad night is discarded by deleting one branch — nothing reached main, nothing was pushed. -In a project that gitignores =.ai/=, the whole spine is untracked, so quiet fires produce no commits at all and =git log main..sentry/<date>-<host>= understates the night's activity. There the anchor's heartbeat list is the only record of what fired. Read the anchor, not just the log. (archangel, first live run 2026-07-21.) +In a project that gitignores =.ai/=, the whole spine is untracked, so quiet cycles produce no commits at all and =git log main..sentry/<date>-<host>= understates the night's activity. There the anchor's heartbeat list is the only record of what fired. Read the anchor, not just the log. (archangel, first live run 2026-07-21.) * Stop Sentry Trigger: "stop sentry" (and synonyms above). Sentry owns its own shutdown: -1. *Cancel the loop* — stop the =/loop= (=ScheduleWakeup= stop / the loop's stop path). No further fires. +1. *Cancel the loop* — stop the =/loop= (=ScheduleWakeup= stop / the loop's stop path). No further cycles. 2. *Release the single-runner lock* if this context holds it. 3. *Branch disposition* — offer, inline-numbered: 1. Squash-merge the day's branch into main now (walk the morning teardown steps 3-5 interactively) @@ -208,14 +208,14 @@ Stopping sentry is the only way to reclaim the working tree mid-night. The entry * Common Mistakes 1. *Running without the =:COMMIT_AUTONOMY:= grant* — sentry commits unattended; the marker is the entry ticket, and its absence is a hard stop, not a degrade. -2. *Starting from a dirty or red tree* — the entry gates exist because an unattended fire can't tell Craig's in-progress work from a regression. Answer the gate; don't bypass it. -3. *Committing onto main* — every writing pass commits to the daily =sentry/*= branch. A fire that finds HEAD off the sentry branch skips rather than commits. +2. *Starting from a dirty or red tree* — the entry gates exist because an unattended cycle can't tell Craig's in-progress work from a regression. Answer the gate; don't bypass it. +3. *Committing onto main* — every writing pass commits to the daily =sentry/*= branch. A cycle that finds HEAD off the sentry branch skips rather than commits. 4. *Running a =git= write against =~/org/roam=* — roam-sync is the only committer. Sentry edits the tree under the roam-write lock and triggers the sync; it never commits or pushes roam. -5. *A per-pass suite run* — the suite runs at entry (baseline) and conditionally at fire-end (only when a pass touched non-org files). Hourly per-commit runs all night is the anti-pattern the suite policy exists to prevent. +5. *A per-pass suite run* — the suite runs at entry (baseline) and conditionally at cycle-end (only when a pass touched non-org files). Hourly per-commit runs all night is the anti-pattern the suite policy exists to prevent. 6. *Executing a judgment or destructive action unattended* — those queue for the morning with their exact command. The pass did its detection; Craig makes the call. The one sanctioned exception is pass 12's solo-task implementation, and only because it inherits work-the-backlog's full defer checklist (data-loss and irreversible actions defer, never execute) plus a premise-verifying review, and it commits to the branch rather than acting on anything live. -7. *A silent skip* — inside a working fire, every skip writes a digest line naming why; a missing pass with no line reads as "ran clean" when it didn't. The one exception is not a violation: an all-quiet fire collapses to a single =sentry at HH:MM: nothing= heartbeat instead of one skip line per pass — the heartbeat is the explicit "nothing to do" record, per the silent-until-signal policy. +7. *A silent skip* — inside a working cycle, every skip writes a digest line naming why; a missing pass with no line reads as "ran clean" when it didn't. The one exception is not a violation: an all-quiet cycle collapses to a single =sentry at HH:MM: nothing= heartbeat instead of one skip line per pass — the heartbeat is the explicit "nothing to do" record, per the silent-until-signal policy. 8. *Degrading a pass to a reduced form* — a pass runs fully or skips. No half-passes. -9. *Letting an unmerged branch stall silently* — after two consecutive unmerged-branch skips, the persistent desktop notify fires. Don't suppress it. +9. *Letting an unmerged branch stall silently* — after two consecutive unmerged-branch skips, the persistent desktop notify cycles. Don't suppress it. 10. *Merging sentry's branch automatically* — the morning teardown is Craig's. Sentry creates and commits; it never merges or deletes its own branch. * Living Document diff --git a/claude-templates/.ai/workflows/startup.org b/claude-templates/.ai/workflows/startup.org index 2262eea..bc89256 100644 --- a/claude-templates/.ai/workflows/startup.org +++ b/claude-templates/.ai/workflows/startup.org @@ -137,39 +137,24 @@ These calls have no dependencies on each other. Issue them all together in one m #+end_src 3. *Sync =.ai/= from templates — but only when the synced source paths in rulesets are clean.* Guard the three rsyncs behind a check that =claude-templates/.ai/{protocols.org,workflows/,scripts/}= have no uncommitted changes. Otherwise Phase A copies in-flight rulesets WIP (tracked edits or new untracked files) into this project's =.ai/workflows/= and =.ai/scripts/=, where it shows up as drift the user didn't author. Skipping once is cheap — the next session with rulesets clean catches up. The check is scoped to the synced paths, so unrelated rulesets dirt (a stray =session-context.org=, scratch files) doesn't needlessly block the sync. A second guard skips the same rsyncs when the *project* branch is behind its upstream (=git rev-list --left-right --count @{u}...HEAD= with =behind > 0=): syncing templates onto a stale committed =.ai/= baseline measures the diff against old content, so it comes out huge and conflicts when the branch later reconciles to upstream, whose history already carries the newer templates. It composes with the rulesets-clean guard — a stable rulesets source and a current project branch are both required before the sync runs. - #+begin_src bash - rs="$HOME/code/rulesets" - synced_dirty=$(cd "$rs" && git status --porcelain -- \ - claude-templates/.ai/protocols.org \ - claude-templates/.ai/workflows/ \ - claude-templates/.ai/scripts/ 2>/dev/null) - # Skip the sync when the project branch hasn't reached its upstream. Syncing - # templates onto a behind baseline measures the diff against stale committed - # .ai/, producing confusing drift that conflicts when the branch reconciles — - # the newer .ai/ is already in upstream. behind==0 (up-to-date or ahead-only) - # means HEAD contains all of upstream, so the baseline is current. No upstream - # (new/unpushed branch) → rev-list fails → proj_behind stays 0, sync runs. - proj_behind=0 - if [ -d .git ]; then - counts=$(git rev-list --left-right --count '@{u}...HEAD' 2>/dev/null) \ - && [ "$(printf '%s' "$counts" | cut -f1)" -gt 0 ] 2>/dev/null \ - && proj_behind=1 - fi + The logic lives in =.ai/scripts/sync-templates=, not inline here. It was extracted 2026-07-31 after an uncommitted edit in rulesets silently blocked all three rsyncs for a full day — five workflow files went stale in one downstream project alone, with nothing anywhere reporting it. A mechanism that distributes correctness fixes to every project needs tests, and inline bash in an org file cannot have them. The behavior is unchanged by the extraction (verified differentially, output and resulting tree both byte-identical); the guards it applies are described below. - if [ -n "$synced_dirty" ]; then - echo "rulesets has uncommitted changes under the synced template paths — skipping .ai/ sync this session (catches up when rulesets is clean):" - echo "$synced_dirty" | sed 's/^/ /' - elif [ "$proj_behind" -eq 1 ]; then - echo "project branch is behind upstream — skipping .ai/ sync this session (templates never land on a stale baseline; the sync runs once the branch is current)" + #+begin_src bash + if [ -x .ai/scripts/sync-templates ]; then + .ai/scripts/sync-templates else - rsync -a "$rs/claude-templates/.ai/protocols.org" .ai/protocols.org - rsync -a --delete "$rs/claude-templates/.ai/workflows/" .ai/workflows/ - rsync -a --delete --exclude='__pycache__' --exclude='.pytest_cache' --exclude='*.pyc' \ - "$rs/claude-templates/.ai/scripts/" .ai/scripts/ - echo ".ai/ synced from templates" + echo "sync-templates not present — .ai/ sync SKIPPED and cannot self-heal; recover with: bash ~/code/rulesets/scripts/audit.sh --apply --force" fi #+end_src + The fallback should never fire in the ordinary rollout. A project still on the pre-extraction startup.org runs the old inline block this session, which delivers both the script and this file together, and the next session finds the script in place. It covers only the split case — the =workflows/= rsync landing while the =scripts/= one didn't — where a project would otherwise hold this file with no script to call. + + *That state does not self-heal, which is why the message names a command.* The fallback runs /instead of/ the sync, so there is no later sync to deliver the missing script: the project would announce one line per session forever while its templates froze. Recovery is out-of-band, via =scripts/audit.sh --apply --force= in rulesets, which rsyncs =scripts/= directly. =--force= is there because audit skips a tracked project holding uncommitted =.ai/= changes, which a project wedged across several sessions is likely to be. + + One caveat on that recovery, worth knowing before running it: audit's =scripts/= rsync carries none of the =__pycache__= / =.pytest_cache= / =*.pyc= excludes this sync does, so it can deposit python cache artifacts that then need removing by hand. Tracked separately; it is a pre-existing gap in audit rather than something this path introduced. + + Announcing the skip loudly with its remedy is the point; a silent skip is the exact failure this extraction exists to stop. + 4. =\ls -t .ai/sessions/ 2>/dev/null | head -5= — list 5 most recent session files. The backslash bypasses any =ls= alias in the user's profile. Without it, bare =ls -t= silently returns no output under =exa= (a common =ls= replacement) — which makes a sessions directory full of files look empty, and the agent then skips Phase B step 2. 5. =\ls -la inbox/ 2>/dev/null= — inventory the inbox. Same reason for the backslash escape, applied uniformly across the Phase A =ls= calls. 6. Read =.ai/notes.org= — Project-Specific Context, Active Reminders, Pending Decisions sections (skip About This File). @@ -213,7 +198,7 @@ These calls have no dependencies on each other. Issue them all together in one m Fleet descriptions ("the fleet is ratio and velox") and runtime derivations ("run =uname -n= to find the hostname") don't match — only current-identity assertions do. Fixture-verified under bash and zsh. -Notes on the rsync commands: +Notes on what =sync-templates= does (the rsync behavior it carries): - Trailing slashes on both source and destination matter — they tell rsync to sync /contents/ rather than nest a directory inside. - =--delete= on the directory syncs lets retired template files actually disappear from each project on next startup. - protocols.org is a single file, no =--delete= needed. diff --git a/claude-templates/.ai/workflows/triage-intake.telegram.org b/claude-templates/.ai/workflows/triage-intake.telegram.org index 5039a8b..1319da5 100644 --- a/claude-templates/.ai/workflows/triage-intake.telegram.org +++ b/claude-templates/.ai/workflows/triage-intake.telegram.org @@ -30,12 +30,27 @@ Telega does not autostart with the Emacs daemon. "Down" is its normal state unless Craig has Telegram open in Emacs. The scan therefore runs the full lifecycle every time, never skips because the server is down: +⚠ *DOWN / not-loaded is the TRIGGER to launch, never a reason to skip or fail.* +This is the exact mistake two projects (work + home, 2026-07-24) made: they +probed telega, saw =(telega-server-live-p)= nil or telega not =featurep=, and +reported =SCAN FAILED: telegram — not loaded= or a silent SKIP — a *blind* +sweep — instead of running Step 1 to start it. A down or unloaded telega is the +normal entry state; =(telega t)= both LOADS the package and STARTS the docker +server (work confirmed: down → =(telega t)= → Ready, 18 chats). So the plugin +MUST run Step 1's launch whenever telega is down/unloaded, wait for Ready, then +scan. =SCAN FAILED= is reserved for a launch that was actually ATTEMPTED and did +not reach Ready (image missing, server crash on start, daemon unreachable) — +never for the pre-launch down state itself. The =:ENABLED:= guard above tests +whether telega is INSTALLED (=fboundp=), not whether the server is up; a down +server never disables the source. + 1. Record prior state: TELEGA_WAS_RUNNING via (telega-server-live-p). 2. Launch (only if not running): emacsclient -e "(progn (setq telega-use-docker t) (telega t) 'started)" - The setq is mandatory defense: tdlib segfaults outside docker mode - (2026-06-09), and Craig's daemon currently has telega-use-docker nil. - Wait ~2s for Ready, then (telega--loadChats 'main) until telega--chats + The setq is mandatory defense: tdlib crashed in native mode when this was + set up (2026-06-09) — a separate matter from the SEGFAULT gotcha, which is + about the loadChats argument — and Craig's daemon defaults to nil. + Wait ~2s for Ready, then (telega--loadChats '(:@type "chatListMain")) until telega--chats is populated. 3. Check messages: the maphash unread scan in ** Scan Step 2 (filters the messageContactRegistered join-notice noise). @@ -48,10 +63,13 @@ lifecycle every time, never skips because the server is down: Verify: telega-server-live-p → nil, no zevlg/telega-server container in docker ps. If Craig had it running, leave it untouched. -If any lifecycle step fails (docker image missing, server crash, daemon -unreachable), the sweep reports it as SCAN FAILED at the top of the summary -per the engine's failure rule — never as a silent skip. Craig gets real -traffic here. +If any lifecycle step fails *after the launch was attempted* (docker image +missing, server crash on start, daemon unreachable, Ready never reached), the +sweep reports it as SCAN FAILED at the top of the summary per the engine's +failure rule — never as a silent skip. This does NOT cover the ordinary +pre-launch down state: a down server means "run Step 1," not "SCAN FAILED." +Craig gets real traffic here, so a blind sweep that skipped the launch is worse +than a clean failure — it hides real unread messages behind a false all-clear. ** Scan @@ -85,22 +103,58 @@ TELEGA_WAS_RUNNING=$(emacsclient -e "(and (fboundp 'telega-server-live-p) (teleg *** Step 1 — start (docker mode) if not already running, wait for Ready #+begin_src bash -# `(telega t)` starts without popping the root buffer. Docker mode (the stable -# path — see the SEGFAULT gotcha) reconnects the persisted ~/.telega session in -# ~2s. Then load the main chat list so telega--chats populates. +# `(telega t)` starts without popping the root buffer. Docker mode reconnects the +# persisted ~/.telega session in ~2s. Then load the main chat list so +# telega--chats populates. +# +# The `(setq telega-use-docker t)` is mandatory and must come BEFORE `(telega t)`: +# tdlib crashed in native mode when this was first set up (2026-06-09), and the +# daemon's default is nil unless something (e.g. an Emacs-config :custom) has +# already forced it. It was missing here while the Quick Reference required it — +# a session that started telega without it on a native-mode daemon would take the +# untested path. Match the Quick Reference exactly. +# +# Note this is a SEPARATE concern from the SEGFAULT gotcha below: that gotcha is +# about the `loadChats` argument, and the deaths it explains happened in docker +# mode. Docker mode is not a defense against it, and it is not evidence for +# docker mode. Keep both. emacsclient -e "(progn + (setq telega-use-docker t) (unless (and (fboundp 'telega-server-live-p) (telega-server-live-p)) (telega t)) 'started)" # Poll until Ready with chats synced, or a crash/timeout. Background this with an # until-loop so the wait doesn't block; exit on Ready-with-chats OR an abnormal # server exit. Then force a chat-list load if the hash is thin: -emacsclient -e "(progn (ignore-errors (telega--loadChats 'main)) (ignore-errors (telega--loadChats 'main)) 'loaded)" +# NOTE: the chat-list argument must be a TL object, not the symbol 'main. +# `telega--loadChats' puts it straight into the request as :chat_list, and a +# bare symbol kills the server outright (see the SEGFAULT gotcha below). +# +# The liveness check on the tail is the load's only failure signal. `ignore-errors' +# catches nothing here, because a bad argument kills the server process rather than +# signalling in elisp, so without this the call returns 'loaded either way. +# The `fboundp' guard matches Step 0: if the launch failed outright telega is not +# loaded, and that should read as 'server-died like any other failure rather than +# signalling void-function. +emacsclient -e "(progn (ignore-errors (telega--loadChats '(:@type \"chatListMain\"))) (ignore-errors (telega--loadChats '(:@type \"chatListMain\"))) (if (and (fboundp 'telega-server-live-p) (telega-server-live-p)) 'loaded 'server-died))" #+end_src On a persisted session telega reaches status "Ready" within ~2s; the chat list loads over a few more. If =(hash-table-count telega--chats)= is 0 or thin, re-issue =telega--loadChats= and poll until it stabilizes. +⚠ *=server-died= is SCAN FAILED, never a quiet account.* A server that dies +during the load leaves a thin =telega--chats= hash, and a thin hash reads exactly +like an account with little unread. That is the same false all-clear the +down/not-loaded rule exists to prevent, arriving one step later in the lifecycle. +It also fits the SCAN FAILED definition above: the launch was attempted and did +not hold. So on =server-died=, report SCAN FAILED rather than scanning, and never +report a low unread count from that run. + +This is the independent evidence the SEGFAULT gotcha asks for when it says to +treat a short chat list as a real short list. Without the check there is no way +to tell the two apart, which is how the =loadChats= crash stayed invisible +through two investigations. + *** Step 2 — read unread, classified by last-message type The single most important filter: =messageContactRegistered=. Telegram counts a @@ -157,24 +211,61 @@ stays non-nil). =telega-server-kill= is what actually stops the server. Call left in =docker ps=. Skipping this whole branch when =TELEGA_WAS_RUNNING= is t is the point of Step 0: never tear down a session Craig is actively using. -⚠ *SEGFAULT GOTCHA — crashes are spontaneous; treat server death as routine.* -The dockerized =telega-server= (=zevlg/telega-server:latest=, image built -2026-06-04, tdlib 1.8.64) SIGSEGVs (exit 139) *on its own*, minutes-to-hours -into a session — 11 host coredumps between 2026-06-09 and 2026-06-11, several at -times when no triage verb was running. The 2026-06-11 investigation reproduced -the crash-free verbs and the spontaneous deaths side by side: coredump -backtraces show a corrupted stack (memory corruption in the musl build), and -no newer image exists upstream. Earlier theories — "native mode is the trigger", -"toggle-read is the trigger" — were timing coincidences; the verbs are sound. +⚠ *SEGFAULT GOTCHA — this was our bug, not tdlib's. Root-caused 2026-07-28.* +=telega-server= dies with =Unexpected char 'm' in plist value= followed by +=Assertion failed: false (telega-dat.c: tdat_plist_value: 500)=. The cause was +this workflow: Step 1 called =(telega--loadChats 'main)=. + +The chain. =telega--loadChats= is a raw TL wrapper — it drops its argument into +the request as =:chat_list= with no conversion. =telega-server--send= then +=prin1='s the whole plist, and =telega--tl-pack= passes atoms through untouched, +so the symbol goes out on the wire bare as =main=. The C parser +(=server/telega-dat.c=, =tdat_plist_value=) accepts only =(=, =[=, ="=, =-=, a +digit, =t=, =:=, or =n= to start a value. It hits =m=, prints that line, and +calls =assert(false)=, which aborts the process. The =m= in the error is +literally the first character of =main=. + +The symbol shorthand is real but belongs to a different layer: +=telega-filter.el= and =telega-folders.el= convert =(eq cl-fspec 'main)= into +='(:@type "chatListMain")=. The raw TL layer never does. telega's own callers +always pass the object (=telega.el:290=, =telega-tdlib-events.el:516=). + +Proved by experiment, not inference (2026-07-28): from a live Ready server, +=(telega--loadChats 'main)= killed it within seconds and added one coredump, +with that exact assertion; a restart plus =(telega--loadChats '(:@type +"chatListMain"))= survived three consecutive calls with no new coredump and no +assertion. + +*The previous entry here was wrong and cost real time.* It recorded the deaths +as spontaneous musl memory corruption and declared "the verbs are sound", which +sent later investigations at the docker image and tdlib versions instead of at +this file. The corrupted stack in the backtraces is what an =assert= abort looks +like, not independent evidence of a memory bug. If crashes are ever seen again +with *no* triage verb running, that is a genuinely separate cause and needs its +own investigation — do not reuse the old spontaneous-crash story to explain it. + +*This crash kills a scan; it does not silently shorten one.* An earlier draft of +this section claimed the reported "19 chats of ~50" was truncation caused by the +bad call. That was wrong, and work disproved it at the wire level on 2026-07-28: +with the corrected call their count is 19 before the first load and 19 after five +(four on =chatListMain=, one on =chatListArchive=). Nineteen is the real size of +that account. The same reading here — 19 stable across three corrected loads — +was already sitting in the evidence and should have retired the claim before it +was written down. Treat a short chat list as a real short list unless something +independently shows the server died mid-sync. + +=ignore-errors= around the call never helped — the failure is the server process +dying, not an elisp signal, so there is nothing for it to catch. That is why the +death is easy to miss from inside elisp, and why a caller should check +=(process-live-p (telega-server--proc))= after a load rather than trusting a +returned value. Operationally: docker mode stays mandatory (=telega-use-docker= = t; the setq before =(telega t)= is still the right defense), and *every action batch checks the server first* — =(process-live-p (telega-server--proc))= — restarting via -=(telega t)= when dead and re-checking Ready before firing verbs. A mid-sweep -death is recoverable, not an abort: restart, confirm Ready, resume. Durable-fix -candidates if the crashing gets worse: pin a pre-2026-06 image digest, build -=telega-server= natively against tdlib, or report upstream to zevlg with the -coredumps (=coredumpctl list /usr/bin/telega-server=). +=(telega t)= when dead and re-checking Ready before firing verbs. Any argument +handed to a =telega--*= TL wrapper must be a TL object or a plain +string/number/list, never a bare symbol. Defense in depth: even if the server does die, the scan still works because it reads the cached =telega--chats= hash, not a live query. A dead server is diff --git a/claude-templates/.ai/workflows/work-the-backlog.org b/claude-templates/.ai/workflows/work-the-backlog.org index a0b24a8..ea3f402 100644 --- a/claude-templates/.ai/workflows/work-the-backlog.org +++ b/claude-templates/.ai/workflows/work-the-backlog.org @@ -54,7 +54,7 @@ For the task set, in order, until the run cap is hit: 1. *Eligibility gate* (below). Ineligible → record =skipped-ineligible=, next task. 2. *Scope read* of the relevant code. Cheap; just enough to run the defer checklist. 3. *Defer checklist* (below). Any hit → defer: file the =VERIFY= naming the gap and record =deferred-VERIFY= (or, under the speedrun preset, route a quick-question gap to the pre-flight Q&A), next task. -4. *Implement* under the project's commit discipline: TDD red→green→refactor, then =/review-code --staged=, fix all Critical/Important findings, then close the task per =todo-format.md='s completion rules. Decompose into as many logical commits as the change needs — size is not capped. If implementation fails partway, leave the tree working, record =failed=, surface it, and continue to the next task. +4. *Implement* under the project's commit discipline: TDD red→green→refactor, then the isolated adversarial review (=publish= Step 1) with its re-review loop, fix all Critical/Important findings, then close the task per =todo-format.md='s completion rules. Decompose into as many logical commits as the change needs — size is not capped. If implementation fails partway, leave the tree working, record =failed=, surface it, and continue to the next task. 5. *Commit autonomy branch:* - =file-only= → surface the diff, do *not* commit. Record =implemented-diff-surfaced=. - =autonomous-commit= → =/voice personal= on the message, commit individually, push per the project's flow. Record =implemented-committed=. @@ -110,7 +110,8 @@ Autonomy changes who approves, not what quality means. Per task, non-negotiable: - *TDD* per =testing.md=: red first, green, refactor. The keystone checklist item already proved the failing test is writable. - *Verification* per =verification.md=: fresh evidence, full suite green before any commit. -- *=/review-code --staged=* before every commit; Critical and Important findings block until fixed. +- *Isolated adversarial review* before every commit, dispatched per the =publish= skill's Step 1 — never an inline self-review, however small the diff. Critical and Important findings block until fixed, and each fix goes back to the *same* reviewer until it approves. Minor findings never earn another round. + - *When the review can't reach approval* — three rounds without it, a finding that recurs after being reported fixed, or a =Needs Discussion= verdict — the unattended run has no one to ask. Record the task =failed= with the standing findings in its result, leave the tree working, and continue to the next task. Never commit past a blocking finding because nobody is awake to adjudicate — an unreviewed commit landing overnight is the outcome this gate exists to prevent. - *=/voice personal=* on every commit message on the =autonomous-commit= path (or the patterns walked inline if the skill is unavailable), message printed inline so the log shows what landed. - *Task closure* per =todo-format.md=: depth-based completion (keyword + =CLOSED:= at level 2, dated rewrite at level 3+). - *One logical change per commit.* A large task becomes several commits, not one omnibus. diff --git a/claude-templates/.ai/workflows/wrap-it-up.org b/claude-templates/.ai/workflows/wrap-it-up.org index d212195..ecd3d22 100644 --- a/claude-templates/.ai/workflows/wrap-it-up.org +++ b/claude-templates/.ai/workflows/wrap-it-up.org @@ -29,6 +29,8 @@ The wrap-up is complete when: The absence of =.ai/session-context.org= is the signal that the last session wrapped up cleanly. Its presence at session start means the previous session was interrupted. +*A helper session meets a shorter list.* Criteria 1 and 2 apply to its own context file (archived under =.ai/sessions/YYYY-MM-DD-HH-MM-<id>-<description>.org=), and 6 applies. Criteria 3, 4, and 5 do not: hygiene, the Linear pass, and all git mutation belong to the primary, so a helper that satisfied criterion 5 would have violated its contract to get there. Step 0 routes this. + * Teardown mode (set from the trigger phrase) The wrap itself — Steps 1 through 5 — is identical in every mode. The trigger phrase only decides what Step 6 does once commit + push and the valediction are done. Resolve the mode from the phrase before starting: @@ -43,7 +45,35 @@ This depends on three functions in =.emacs.d/modules/ai-term.el= (=cj/ai-term-qu * The Workflow -** Step 0: Refuse if sentry is live +** Step 0: Helper branch — a helper wraps only itself + +Resolve first whether this session is a helper, because a helper's wrap is a different and much shorter workflow. Everything from Step 1 down — the hygiene passes, the inbox check, the commit, the push, the clean-tree certificate — is primary-only under the role contract in [[file:helper-mode.org][helper-mode.org]], and running any of it from a helper is exactly the concurrency failure that contract exists to prevent. + +A session is a helper when =AI_HELPER=1= in its environment (=ai --helper= sets it) or when it adopted helper-mode.org this session by instruction. If neither holds, this is a primary: skip to Step 0.5 and wrap normally. + +#+begin_src bash +echo "AI_HELPER=${AI_HELPER:-unset} AI_AGENT_ID=${AI_AGENT_ID:-unset}" +#+end_src + +For a helper, re-run the roster — the answer decides which wrap applies: + +#+begin_src bash +root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" +if [ -x "$root/.ai/scripts/agent-roster" ]; then + "$root/.ai/scripts/agent-roster" "$root"; rc=$? +else + rc=2 +fi +echo "roster rc=$rc" +#+end_src + +Pass the project root explicitly. =agent-roster= defaults to =$PWD= and keeps only agents whose cwd is at or inside that root, so running it from a subdirectory hides a primary sitting at the root — and the "alone" that produces is read below as *orphaned*, which is the one branch that commits and pushes. Capture =rc= inside the branch too: =[ -x … ] && …; echo $?= reports the status of the whole list, so an absent script reads as 1 (others live) rather than 2 (unavailable). + +- *Primary still live (rc 1)* — the normal case. Finalize the =* Summary= in the helper's own context file — same contract as Step 1, KB receipt line included (resolve it with =AI_AGENT_ID=<id> .ai/scripts/session-context-path=), archive it to =.ai/sessions/YYYY-MM-DD-HH-MM-<id>-<description>.org= so it can't collide with the primary's archive name, deliver the valediction, and stop. Do NOT commit, push, or run any hygiene pass. The helper's scoped edits stay in the tree and the primary's next commit carries them along with the archived file — say so in the valediction, so Craig knows the work is real but not yet pushed. +- *Alone (rc 0) — orphaned helper* — the primary exited first, so the git ban lifts: the concurrency that justified it is gone, and stopping here would strand the helper's edits as a dirty tree nobody owns. Run the full wrap below starting at Step 0.5, exactly as a primary would. +- *Roster unavailable (rc 2, or the script absent)* — take the archive-only path, the same as primary-still-live. Leaving work for the next session to commit is recoverable; guessing "orphaned" and committing underneath a live primary is not. + +** Step 0.5: Refuse if sentry is live Before anything else, check whether sentry is running in this project. Sentry holds the working tree on its =sentry/<date>-<host>= branch and commits unattended; wrapping underneath it would archive the session anchor and tear down the buffer while the loop is still firing into it. If sentry's single-runner lock is held, stop and point at the shutdown path: @@ -55,7 +85,7 @@ if [ -x .ai/scripts/agent-lock ] && .ai/scripts/agent-lock status "sentry-$proj" fi #+end_src -The stop-sentry operation (defined in =sentry.org=) owns the shutdown: it cancels the loop, disposes of the branch, and walks the approval queue. Wrap-up carries only this one guard; a =stale= lock (a crashed fire) doesn't block — only a live =held= lock does. +The stop-sentry operation (defined in =sentry.org=) owns the shutdown: it cancels the loop, disposes of the branch, and walks the approval queue. Wrap-up carries only this one guard; a =stale= lock (a crashed cycle) doesn't block — only a live =held= lock does. ** Step 1: Finalize the Summary diff --git a/claude-templates/bin/ai b/claude-templates/bin/ai index 65d0ab7..3440ee2 100755 --- a/claude-templates/bin/ai +++ b/claude-templates/bin/ai @@ -18,6 +18,17 @@ # ollama; model per AI_LOCAL_MODEL, default gpt-oss:120b). # Also settable via AI_RUNTIME. # +# ai --helper <dir> Open a SECOND session in a project that already has a +# live one, under the helper-mode.org role contract: reads +# freely, makes only scoped edits, never mutates git, and +# skips git prep because the primary owns pulls. Runs +# agent-roster first — with no other agent live it warns +# and falls back to a normal primary launch (which does +# run git prep). Run it from a terminal of your own: the +# roster excludes its caller's own process ancestry, so +# invoking it from inside an agent session hides that +# session and silently downgrades to a primary launch. +# # ai --attach Attach to the existing 'ai' session without changes. # # ai -h | --help Show this help. @@ -110,8 +121,18 @@ build_instructions() { printf 'This is %s %s project. Follow all instructions in .ai/protocols.org.' "$(uname -n)" "$name" } +# The opening line for a helper session. Deliberately does NOT name +# protocols.org: a helper must not run normal startup (pulls, rsync, inbox +# processing all belong to the primary), and helper-mode.org sends it to +# protocols.org itself once the role contract is loaded. +build_helper_instructions() { + local name="$1" + printf 'This is %s %s project. You are a helper session: another agent is already live here. Read and follow .ai/workflows/helper-mode.org — it is your role contract. Do not run the normal startup workflow.' \ + "$(uname -n)" "$name" +} + usage() { - sed -n '2,23p' "$0" | sed 's|^# \?||' + sed -n '2,34p' "$0" | sed 's|^# \?||' exit 0 } @@ -146,14 +167,92 @@ _git_prep_action() { fi } +# Decide what a `--helper` launch actually becomes, from the roster's verdict. +# Input is agent-roster's exit status — 0 alone, 1 others live, 2 unavailable — +# or the literal "absent" when no roster script is installed. Echoes one of: +# helper — confirmed: another agent is live here +# primary — refuted: nobody else is here, so --helper is a no-op +# helper-unverified — the roster couldn't answer +# Unverifiable resolves toward helper on purpose. `--helper` is the operator +# asserting a primary is live, and helper mode is the strictly less destructive +# guess: a helper that turns out to be alone merely does less, while a primary +# that turns out not to be alone runs pulls and rsync under a live session. +_helper_launch_mode() { + case "$1" in + 1) echo helper ;; + 0) echo primary ;; + *) echo helper-unverified ;; + esac +} + +# A helper's agent id: helper-<rand4>, per helper-mode.org's identity rule. +# Four hex digits is enough — the id only has to be unique among the agents +# live in one project at one moment, and the archived session file carries the +# date and time as well. Two draws because bash's RANDOM is 15-bit, so a single +# one would never set the top bit and the first hex digit would always be 0-7. +_helper_id() { + printf 'helper-%04x\n' $(( ((RANDOM << 1) ^ RANDOM) & 0xffff )) +} + +# Reduce an id to the characters session-context-path keeps, so the launcher and +# the path resolver agree on what a given id means. This is also a safety fix, +# not just tidiness: the id is interpolated into the command line typed into the +# pane, so an id carrying a space or a ';' would split the assignment off from +# the command and run something else instead of launching the helper. +# printf without a newline on purpose: tr -c would translate a trailing newline +# into an underscore too, silently appending one to every sanitized id. +_sanitize_agent_id() { + printf '%s' "$1" | tr -c 'A-Za-z0-9._-' '_' + printf '\n' +} + +# Resolve the id for a helper launch: an explicitly-exported one when it is +# free, otherwise a fresh one. +# +# The reuse check is the load-bearing part. A helper's own pane exports +# AI_AGENT_ID, so `ai --helper` invoked from inside a helper inherits its +# parent's id rather than being given one deliberately. Honoring that blindly +# points two live agents at one .ai/session-context.d/<id>.org, which is the +# lost-update collision the whole helper contract exists to avoid. +_resolve_helper_id() { + local dir="$1" + local want="${AI_AGENT_ID:-}" + local tries=0 + + if [ -n "$want" ]; then + want="$(_sanitize_agent_id "$want")" + if [ ! -e "$dir/.ai/session-context.d/$want.org" ]; then + printf '%s\n' "$want" + return + fi + echo "ai: agent id '$want' is already live in $(basename "$dir") — assigning a fresh one" >&2 + fi + + # A minted id gets the same free-anchor check as a supplied one. The odds of + # a chance collision are small, but a guard that only covers the path the + # caller controls leaves the collision it exists to prevent reachable. + # Bounded so a full or unreadable directory can't spin here. + while [ "$tries" -lt 8 ]; do + want="$(_helper_id)" + [ -e "$dir/.ai/session-context.d/$want.org" ] || break + tries=$((tries + 1)) + done + printf '%s\n' "$want" +} + # Re-order "name<TAB>wid" lines (stdin) into the launcher's window order: # non-project windows alphabetically, then project windows alphabetically. # $1 is a newline-separated list of project window names. +# +# A helper window is named "<project>:<agent-id>", so it matches on the prefix +# before the first colon rather than on the whole name. That keeps it sorted +# next to the project it helps instead of landing among the unrelated windows. _order_windows() { local project_names="$1" wname wid others="" projects="" while IFS=$'\t' read -r wname wid; do [ -z "$wname" ] && continue - if printf '%s\n' "$project_names" | grep -qxF "$wname"; then + if printf '%s\n' "$project_names" | grep -qxF "$wname" || + printf '%s\n' "$project_names" | grep -qxF "${wname%%:*}"; then projects+="${wname}"$'\t'"${wid}"$'\n' else others+="${wname}"$'\t'"${wid}"$'\n' @@ -394,6 +493,36 @@ prep_git_single() { esac } +# Run the project's agent-roster and turn its verdict into a launch decision. +# The decision is the only thing on stdout; warnings go to stderr so callers +# can capture one without the other. +_resolve_helper_launch() { + # Two statements on purpose: a name assigned in a `local` is not yet visible + # to a later assignment in that same `local`, so building the roster path in + # this line would read the CALLER's $dir — right only by coincidence. + local dir="$1" + local roster="$dir/.ai/scripts/agent-roster" rc decision + if [ -x "$roster" ]; then + # The roster prints the other agents it found; only its exit code matters + # here, and its stdout must not reach a --print-launch caller's output. + "$roster" "$dir" >/dev/null 2>&1 + rc=$? + else + rc=absent + fi + + decision="$(_helper_launch_mode "$rc")" + case "$decision" in + primary) + echo "ai: --helper found no other agent live in $(basename "$dir") — opening a normal primary session instead" >&2 + ;; + helper-unverified) + echo "ai: could not verify another agent is live in $(basename "$dir") — roster unavailable; opening a helper anyway" >&2 + ;; + esac + echo "$decision" +} + # ---------- modes ---------- attach_mode() { @@ -447,6 +576,55 @@ single_mode() { attach_session } +# Open a helper session: a second agent in a project that already has a live +# one. Two deliberate differences from single_mode. It never focuses an +# existing window — a second session is the entire point, and focusing the +# primary's window is the one outcome that can't be what was asked for. And it +# never runs git prep, because every pull belongs to the primary under the +# helper contract. +helper_mode() { + local arg="$1" dir name id wid wname decision instructions + dir="$(cd "$arg" 2>/dev/null && pwd)" || { + echo "ai: cannot access '$arg'" >&2 + return 1 + } + + if [ ! -f "$dir/.ai/protocols.org" ]; then + echo "ai: $dir has no .ai/protocols.org — not an agent-template project" >&2 + return 1 + fi + + name="$(basename "$dir")" + + # Nobody else is here, so there is nothing to be a helper to. Fall through to + # the normal launch rather than opening a crippled session. + decision="$(_resolve_helper_launch "$dir")" + if [ "$decision" = primary ]; then + single_mode "$arg" + return $? + fi + + id="$(_resolve_helper_id "$dir")" + wname="$name:$id" + instructions=$(build_helper_instructions "$name") + + if tmux has-session -t "$SESSION" 2>/dev/null; then + wid=$(tmux new-window -a -t "$SESSION:{end}" -n "$wname" -c "$dir" -P -F '#{window_id}') + sleep 0.1 + else + wid=$(tmux new-session -d -s "$SESSION" -n "$wname" -c "$dir" -P -F '#{window_id}') + fi + + # The id rides in the launched process's environment, which is what + # session-context-path reads to resolve .ai/session-context.d/<id>.org. + tmux send-keys -t "$wid" \ + "${LAUNCH_PREFIX}AI_AGENT_ID=$id AI_HELPER=1 $AGENT_CMD \"$instructions\"" Enter + + sort_windows + tmux select-window -t "$wid" + attach_session +} + # Multi-select via fzf (the original aix flow). multi_mode() { local filtered=() selections first_wid="" @@ -537,6 +715,15 @@ print_launch_mode() { exit 1 fi name="$(basename "$dir")" + + # The roster runs here too, so the printed line reflects the decision a real + # run would make — including the downgrade to a primary launch. + if [ -n "$HELPER_MODE" ] && [ "$(_resolve_helper_launch "$dir")" != primary ]; then + printf 'AI_AGENT_ID=%s AI_HELPER=1 %s "%s"\n' \ + "$(_resolve_helper_id "$dir")" "$AGENT_CMD" "$(build_helper_instructions "$name")" + exit 0 + fi + printf '%s "%s"\n' "$AGENT_CMD" "$(build_instructions "$name")" exit 0 } @@ -549,12 +736,17 @@ print_launch_mode() { # dispatch runs exactly as before; when sourced, it's skipped. main() { print_launch="" + HELPER_MODE="" runtime_explicit="${AI_RUNTIME:+1}" while [ $# -gt 0 ]; do case "$1" in -h | --help) usage ;; + --helper) + HELPER_MODE=1 + shift + ;; --runtime) [ -z "${2:-}" ] && { echo "ai: --runtime needs a value — valid runtimes: claude, codex, local" >&2 @@ -585,6 +777,13 @@ main() { resolve_agent_cmd + # A helper is always scoped to one named project. There is no roster to check + # and no primary to help without one, so this can't fall back to the picker. + if [ -n "$HELPER_MODE" ] && [ -z "${1:-}" ]; then + echo "ai: --helper needs a project directory" >&2 + exit 2 + fi + if [ -n "$print_launch" ]; then [ $# -eq 0 ] && { echo "ai: --print-launch needs a project directory" >&2 @@ -610,7 +809,11 @@ main() { *) check_deps for arg in "$@"; do - single_mode "$arg" + if [ -n "$HELPER_MODE" ]; then + helper_mode "$arg" + else + single_mode "$arg" + fi done ;; esac diff --git a/inbox/lint-followups.org b/inbox/lint-followups.org index f63470c..21a5ed3 100644 --- a/inbox/lint-followups.org +++ b/inbox/lint-followups.org @@ -1,17 +1,18 @@ * 2026-07-20 Mon — Task-review health: 1 top-level [#A]/[#B]/[#C] tasks unreviewed for >30 days (daily review may have slipped) -* lint-org follow-ups — todo.org (2026-07-25) -** TODO link-to-local-file — Link to non-existent local file "working/hook-fail-open/validate-el.diff" (line 2066) -** TODO misplaced-planning-info — Misplaced planning info line (line 2055) -** TODO link-to-local-file — Link to non-existent local file "working/hook-fail-open/pre-commit.diff" (line 2050) -** TODO misplaced-planning-info — Misplaced planning info line (line 2035) -** TODO org-table-standard — table violates the org-table standard: no closing rule; missing rule between rows — wrap-org-table.el reflows it (line 141) -** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 299) -** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 302) -** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 309) -** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 317) -** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 320) -** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 329) -** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 427) -** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 586) -** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 595) +* lint-org follow-ups — todo.org (2026-07-31) +** TODO misplaced-heading — Possibly misplaced heading line (line 2320) +** TODO link-to-local-file — Link to non-existent local file "working/hook-fail-open/validate-el.diff" (line 2296) +** TODO misplaced-planning-info — Misplaced planning info line (line 2285) +** TODO link-to-local-file — Link to non-existent local file "working/hook-fail-open/pre-commit.diff" (line 2280) +** TODO misplaced-planning-info — Misplaced planning info line (line 2265) +** TODO org-table-standard — table violates the org-table standard: no closing rule; missing rule between rows — wrap-org-table.el reflows it (line 371) +** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 529) +** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 532) +** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 539) +** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 547) +** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 550) +** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 559) +** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 657) +** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 816) +** TODO task-missing-last-reviewed — task has no :LAST_REVIEWED: — stamp it at creation with today's date (a task you just wrote and graded is reviewed); otherwise it enters the next staleness batch as never-reviewed (line 825) diff --git a/publish/SKILL.md b/publish/SKILL.md index 48924b7..d2b906c 100644 --- a/publish/SKILL.md +++ b/publish/SKILL.md @@ -222,28 +222,142 @@ Step 0. Upstream can advance during a long session, especially across machines or with teammates pushing in parallel. Run Step 0 every time the publish flow starts. -### Step 1: local code review (mandatory) - -Run the `review-code` skill against the change: - -- Before a commit: `/review-code --staged` -- Before a PR: `/review-code` (branch diff against `main` merge-base) -- Before commenting on someone else's PR: `/review-code <PR#>` - -Surface **all** findings to the user: Critical, Important, and Minor. - -**Default block:** any Critical or Important finding stops the flow. Fix the -issues and re-run `/review-code` until the diff is clean. Minor findings are -shown but do not block. - -**Override:** the user can bypass the block with an explicit "proceed anyway" -(or equivalent wording). Without the explicit override, do not proceed to -Step 2. - -The `review-code` skill already has a Phase 0 eligibility gate that handles -trivial and ineligible diffs (whitespace-only, revert with obvious -justification, already-reviewed SHA). Trust that gate; there is no "trivial -enough to skip review" exemption on top of it. +### Step 1: adversarial review by an isolated reviewer (mandatory) + +The review runs in a **subagent**, never inline, and it runs on **every** +commit. The author does not review their own work. + +**Why isolation, not just review.** A self-review checks the diff against the +author's own model of what the diff should do. It cannot check the model. The +errors that survive a self-review are the ones that were never visible in the +diff — a scope inherited from whoever reported the problem, a blast radius +estimated instead of measured, a fix that is correct for the case the author +had in mind and wrong for the one they never considered. Only a reviewer that +does not hold the author's model catches those, so the isolation is the point +and the adversarial stance is the method. + +**Dispatch contract.** Spawn the reviewer via the Agent tool and give it these +three things, the third whenever one exists: + +1. **The diff** — `git diff --cached` for a commit, the branch diff for a PR. +2. **The claim** — one line from the author stating what the change does. Write + it before dispatching. This is the thing under test: the reviewer's job is + to check the diff against the claim. +3. **The requirement source, when one exists** — the ticket, plan, ADR, or task + body the work was done against. Pass it verbatim. + +Withhold everything else: the conversation, the exploration, the dead ends, and +above all the author's reasoning for why the change is right. Those are what +transmit the author's model, which is what the reviewer exists to not have. A +reviewer given the rationale reviews the rationale. + +**Why the requirement source is not withheld.** A ticket or plan is not the +author's model of the change — it is the independent record of what was asked, +written before the work and usually by someone else. It is the only artifact +that can contradict the author's one-line claim. Withhold it and the claim +becomes self-certifying: the reviewer checks the diff against a sentence the +author wrote, which cannot surface scope creep or a missing requirement. That +also strands `review-code`'s Intent-vs-Delivery criterion, which is skipped +outright when no intent context is supplied and is the one criterion aimed at +the inherited-scope error this whole gate exists to catch. + +Invoke the review with `/review-code --staged` (commit), `/review-code` (branch +diff against the `main` merge-base), or `/review-code <PR#>` (someone else's +PR), and tell it to run its adversarial pass. + +**Adversarial, with substantiation.** The reviewer is prompted to *refute* the +change rather than to bless it. But an agent told to attack will manufacture +findings to satisfy the instruction, so the stance carries a floor: a finding +that cannot be substantiated against the diff is not a finding and must be +dropped. `review-code`'s confidence filter and false-positive filter are what +enforce that floor — adversarial raises the appetite for looking, never the +tolerance for a weak claim. + +**Scope is every commit; the reviewer decides triviality, not the author.** +There is no "trivial enough to skip" exemption. A floor written in terms of +"small" or "mechanical" puts the judgment back with the author, whose judgment +is the thing being checked. Dispatch always, and let `review-code`'s own Phase 0 +eligibility gate return fast on a whitespace-only diff, an obvious revert, or an +already-reviewed SHA. A cheap spawn on a trivial commit is the price of the +author never getting to rule on their own diff. + +**Verdict, and the re-review loop.** The reviewer returns one of four outcomes, +and all four are defined exits: + +- **Approve** — the gate is satisfied. Proceed to Step 2. +- **Skipped** — `review-code`'s Phase 0 found the diff ineligible (whitespace + only, an obvious revert, an already-reviewed SHA). This **satisfies the gate** + and the flow proceeds. A skip is a reviewer's ruling, which is the point; what + is forbidden is the *author* ruling their own diff too trivial to look at. +- **Request Changes** — blocking findings stand. Enter the loop below. +- **Needs Discussion** — the reviewer has a disagreement it cannot settle from + the diff: an architectural objection, a question about whether the change + should exist at all. This **stops immediately and goes to the user**; it does + not enter the loop. Routing it to the loop would answer "should we do this?" + with "fix these findings," which is the wrong question and burns rounds on a + disagreement no amount of editing resolves. Unattended callers park it exactly + as they park a bound hit. + +Approval is the reviewer's to give; the author never declares their own change +clean. + +That set is closed. `review-code` emits Approve, Request Changes, or Needs +Discussion, and its Phase 0 emits Skipped; every one has a defined exit above. A +verdict outside those four means the reviewer went off-contract — surface it +rather than interpreting it. + +**The loop turns on blocking findings, not on the verdict token.** It ends when +no Critical or Important finding stands. A Minor-only result is not grounds for +another round: fix it or don't, but do not spend a round on it, and do not +escalate to the user over one. A reviewer holding only Minor findings should +return Approve and say what it left. + +On Request Changes: + +1. Surface **all** findings — Critical, Important, Minor. Critical and Important + block; Minor is shown and does not block. +2. Fix the blocking findings. +3. **Re-review, and keep re-reviewing until the reviewer approves.** A fix is a + new change and gets the same scrutiny as the original. Fixing under review + pressure is exactly when a regression gets introduced, so an unreviewed fix + is the hole this loop closes. + +**Continue the same reviewer, don't spawn a fresh one.** Send the updated diff +back to the existing reviewer (`SendMessage` with its agent ID). It holds its own +findings, so it can confirm each one is actually addressed. A fresh reviewer each +round cannot tell "addressed" from "never existed", re-litigates settled points, +and drifts to a new set of findings every round, which never converges. + +The continued reviewer must **re-verify each finding against the new diff**, not +against the author's description of the fix. "I fixed it" is a claim, and taking +it at face value is how a review round becomes a rubber stamp. + +**Bounds, so the loop terminates.** Two conditions end it early and hand the +decision to the user: + +- **Three rounds without approval** (the initial review plus two re-reviews). + This matches the two-fix-attempts limit in `subagents.md`: past that, the + problem is usually the approach rather than the diff. +- **A finding recurs after being reported fixed.** That is oscillation — the + fix for one finding reintroducing another — and another round will not + resolve it. Stop on the first recurrence rather than spending the remaining + rounds. + +In both cases, stop and surface: the standing findings, what was tried, and the +decision needed. + +**Override.** The user can bypass the block with an explicit "proceed anyway" (or +equivalent). The user is also the adjudicator when the author believes a finding +is wrong: say so with the reasoning and let the user rule. Do not resolve a +disagreement with the reviewer by overruling it silently. Without an explicit +override, do not proceed to Step 2. + +**When the Agent tool is unavailable.** Per `subagents.md`, don't block: run the +review in the main thread, but hold it to the same contract — review against the +stated claim, refute rather than bless, substantiate every finding, loop on fixes +until clean, same bounds. State plainly that the review was not isolated, because +a self-review under an adversarial prompt is weaker evidence and the user should +know which one they got. ### Step 2: draft, review, publish @@ -251,16 +365,37 @@ enough to skip review" exemption on top of it. *Voice patterns are always personal for publish artifacts.* Commit messages, PR titles + bodies, and PR review comments all go out under the user's name, so they always run through `/voice personal` (the full pattern walk — general + Craig's-voice + the artifact-mechanics patterns: first-person rewrite, public-artifact scope flag, praise/correction asymmetry, finding stems), regardless of whether `.ai/` is tracked. These three are personal-voice artifacts by definition — the skill's personal mode exists for exactly them. Pattern #39 (public-artifact scope flag) matters *most* on team-visible artifacts, so it must never be skipped on a PR comment or PR body. There is no "general-voice mode" for publish artifacts. -*The approval gate is the only thing `.ai/`-tracking decides.* Before drafting, run this command: +*The approval gate turns on whether anyone else reads the history.* The gate +exists so Craig sees the exact words that go out under his name. Skipping it +trades that for velocity, and that trade is only worth making where the repo is +genuinely shared with other people. + +The old signal for this was whether `.ai/` is tracked, used as a proxy for +"team repo." It was the wrong proxy and it failed in the direction that +matters: rulesets, home, and work all track `.ai/` — rulesets as a committed +mirror, the others because the project history *is* the project — while all +three are Craig's private single-user repos. The rule as written skipped the +gate on his three most-used projects. + +Check the remote host instead, which is what actually distinguishes them: ``` -git ls-files :/.ai/ 2>/dev/null | head -1 +git remote -v 2>/dev/null | grep -v 'cjennings\.net' | head -1 ``` -The `:/` pathspec anchors the search to the repo root, so the command works from any subdirectory. Without it, running from a subdir returns no matches even when `.ai/` is tracked at the repo root, which silently misclassifies the project. +- **No output** — every remote is on `cjennings.net`, so the repo is Craig's + own and nobody else reads the log. **Gate applies**: write to `/tmp`, run + `/voice personal`, print inline, ask approve / request changes / open in + editor, and publish only on explicit approval. +- **Any output** — a remote on a host someone else can read (GitHub, a GHE + instance, a team server). **Gate skipped for velocity**: write to `/tmp`, run + `/voice personal`, print inline, publish immediately. +- **No remote at all** — a local-only repo. Gate applies; there is no + velocity argument without a reader. -- **No output** — `.ai/` is gitignored, missing, or empty (the user's personal repos). **Gate applies**: write to `/tmp`, run `/voice personal`, print inline, ask approve / request changes / open in editor, then publish only on explicit approval. -- **Any output** — one or more files under `.ai/` are tracked (a shared / team repo). **Gate skipped for velocity**: write to `/tmp`, run `/voice personal`, print inline, publish immediately. +As of 2026-07-27 every project resolves to gate-applies, because every remote +is `cjennings.net`. That is the correct answer, not a bug: it matches how the +flow has actually been run. Either way the draft runs through `/voice personal` first. The subflows below describe the full gated path. For the gate-skipped path, run the same `/voice personal` pass, then collapse the "Ask: approve, request changes, or open in editor" step — the draft prints inline and the publish step runs immediately afterward. @@ -274,108 +409,22 @@ Either way the draft runs through `/voice personal` first. The subflows below de - **Request changes** → make them, re-run `/voice personal`, re-print inline, ask again. - **Open in editor** → only if the user asks. `emacsclient -n /tmp/commit-<short-slug>.md`. After the editor closes, re-read the file, re-print the contents inline, and ask again. -**For PR descriptions:** - -1. Write the title as line 1 and the body below it to `/tmp/pr-<slug>.md`. **Title format:** the conventional-commit subject (`refactor: remove dead if-count-is-not-None check in admin`). If the project defines a publishing overlay with a ticket system, follow it for the ticket suffix in the title and the cross-link line in the body (see the overlay). -2. Run `/voice personal` on the file. The PR title stays imperative per Conventional Commits — `/voice personal` rewrites the body, not the title. -3. Print the final draft inline in the terminal. Title on line 1, blank line, then body — exactly as it'll be posted. State that the skill ran. Surface any pattern #39 (public-artifact scope) warnings. -4. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default. - - **Approve** → continue to step 5. - - **Request changes** → make them, re-run `/voice personal`, re-print inline, ask again. - - **Open in editor** → only if the user asks. `emacsclient -n /tmp/pr-<ticket-or-slug>.md`. After the editor closes, re-read the file, re-print inline, ask again. -5. Split the file on the first blank line and pass the title and body to `gh pr create --title "..." --body "$(tail -n +3 <file>)"` (or a heredoc) so formatting is preserved. Add `--reviewer <user[,user...]>` in the same call when you already know who should review. -6. Request reviewers on the new PR if you didn't pass `--reviewer` at create time. Use `gh pr edit <N> --add-reviewer <user>`. If the repo has a `CODEOWNERS` file, GitHub auto-suggests based on touched paths. Still issue the explicit request so the reviewer gets notified. Pick reviewers per the team's convention for the area touched (often documented in the per-repo `CLAUDE.md`). For follow-up PRs, consider tagging the parent PR's author if their context would help. PRs without a human reviewer request stall — "checks passed" is not a substitute for review. -7. **Project publishing overlay (if present).** If the project defines a publishing overlay — a `publishing-<team>.md` rule loaded from its `.claude/rules/` — run its post-create steps now: ticket cross-linking, ticket-state moves, and any other tracker integration it specifies. A project with no overlay skips this; the PR is already open and reviewers are requested, which is the complete universal flow. - -**For PR review comments and replies (review verdicts, threaded discussion, follow-up notes on someone else's PR or your own):** - -Pick the shape first. Most reviews are Shape 1. - -- **Shape 1 — Single review** (verdict + summary body + 0+ inline pins). The default for any post that carries a verdict (`APPROVE`, `REQUEST_CHANGES`, `COMMENT`), even when the verdict has no line-specific findings. One `gh api` call posts the summary, every inline pin, and the verdict together. review notification fires once for `APPROVE` or `REQUEST_CHANGES`. -- **Shape 2 — Issue-thread comment** (no verdict). General PR discussion, not a review. No inline pins. No review notification. -- **Shape 3 — Reply on an existing inline thread**. Responding to a specific prior reviewer comment. Threads under that comment. No review notification. - -**Inline threshold for Shape 1.** Any finding that names a `path:line` belongs as an inline comment pinned to that line. Cross-cutting observations (verdict rationale, "third PR with the same pattern", overall test-coverage gaps that don't pin to one place) stay in the summary body. There's no "fold one inline into the summary" exception — a single line-specific finding still goes inline. - -**Shape 1: Single review (bundled summary + inline)** - -1. Identify findings, split into **inline-eligible** (each names a specific `path:line`) and **summary-only** (cross-cutting). Decide the verdict. - -2. Write one concatenated draft to `/tmp/pr-<N>-review.md` with explicit separators: - - ``` - === SUMMARY === - <verdict summary body> - - === INLINE path=frontend/src/foo.tsx line=440 === - <inline body 1> - - === INLINE path=frontend/src/bar.tsx line=137 === - <inline body 2> - ``` - - The separator format is exactly `=== SUMMARY ===` and `=== INLINE path=<path> line=<n> ===`. The summary block is mandatory even for verdict-only reviews. Inline blocks are zero-or-more. - -3. Run `/voice personal` on the file once. The skill walks its full pattern list across every block at the same time. The separators stay intact because they aren't prose. - -4. Print the final draft inline in the terminal. Every block — the summary body AND the full prose of every inline comment — exactly as it'll be posted, with its separator header. Print the inline in full; never describe it in place of printing it ("I'd pair it with one inline on…"). Craig approves the exact words that post under his name, so the exact words must be on screen. State that the skill ran (e.g. "/voice personal — full pattern walk across summary + 3 inline"). Surface any pattern #39 warnings. - -5. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default. - - **Approve** → continue to step 6. - - **Request changes** → make them, re-run `/voice personal` on the whole file, re-print inline, ask again. - - **Open in editor** → only if the user asks. `emacsclient -n /tmp/pr-<N>-review.md`. After the editor closes, re-read, re-print inline, ask again. - -6. Split the file on the separator lines and post in **a single** `gh api` call: - - ``` - gh api repos/<owner>/<repo>/pulls/<N>/reviews \ - --hostname <ghe-host-or-omit> \ - -F event=REQUEST_CHANGES \ - -F body="<summary block>" \ - -F "comments[][path]=<path1>" \ - -F "comments[][line]=<line1>" \ - -F "comments[][body]=<inline 1>" \ - -F "comments[][path]=<path2>" \ - -F "comments[][line]=<line2>" \ - -F "comments[][body]=<inline 2>" - ``` - - `event` is one of `APPROVE`, `REQUEST_CHANGES`, `COMMENT`. The `comments[]` array can be empty for verdicts with zero line-specific findings — the call still uses the same endpoint. Pass `--hostname` for non-`github.com` hosts (a project's publishing overlay names its host when it's a GitHub Enterprise instance). - -7. Verify the review landed. `gh api repos/<owner>/<repo>/pulls/<N>/reviews --hostname ...` returns the latest review with bundled inlines. Confirm `state` matches the verdict and the inline count matches what was posted. - -8. **Project review-notification overlay (if present).** If the project defines a publishing overlay with a review-notification step (e.g. a Slack ping to the PR author), run it now — but only for `APPROVE` and `REQUEST_CHANGES` verdicts. The overlay owns the channel, the message format, the author-mention lookup, and the threading. A project with no overlay skips notification entirely. `COMMENT` verdicts and Shapes 2-3 below never notify, overlay or not. - -**Shape 2: Issue-thread comment (no verdict)** - -Use when the post is informal discussion that shouldn't appear as a review verdict (e.g. "I'd like to discuss the X approach before you continue"). - -1. Write the proposed comment to `/tmp/pr-<N>-comment.md`. -2. Run `/voice personal`. -3. Print inline, ask approve/changes/edit, gate as in Shape 1 step 5. -4. Post: `gh pr comment <N> --body-file /tmp/pr-<N>-comment.md`. -5. Verify: `gh api repos/<owner>/<repo>/issues/<N>/comments`. -6. No review notification. - -**Shape 3: Reply on an existing inline thread** - -Use when responding to a specific prior reviewer comment. - -1. Find the parent comment ID: `gh api repos/<owner>/<repo>/pulls/<N>/comments`. -2. Write the reply to `/tmp/pr-<N>-reply-<comment-id>.md`. -3. Run `/voice personal`. -4. Print inline, ask approve/changes/edit, gate as in Shape 1 step 5. -5. Post: `gh api repos/<owner>/<repo>/pulls/<N>/comments -F in_reply_to=<comment-id> -F body="$(cat /tmp/pr-<N>-reply-<comment-id>.md)"`. -6. Verify in the same `comments` list. -7. No review notification. +**For PR descriptions, and for PR review comments and replies:** read +`references/pull-requests.md` in this skill directory. It carries the PR +description shape, the three review shapes (bundled review with inline pins, +issue-thread comment, threaded reply), the `gh api` calls, and the +publishing-overlay hooks. A plain commit needs none of it, so it is kept out of +this file — load it when the artifact is a PR. **Approve does not authorize a merge.** Reviewing a PR never authorizes merging it. Anything in `## Merge Strategy` below applies only to merges *you* are about to perform on your own branches — and even then, the merge needs its own explicit user confirmation per the rules there. A project's publishing overlay may add a team merge practice (e.g. approve-then-author-merges, where the review notification hands the merge decision to the PR author); that's an overlay concern, not a global one. **Exception:** trivial one-liners the user dictated verbatim in the conversation (e.g. "commit this as `chore: bump version`", "reply just 'thanks for the review'") can skip the draft-file step in Step 2. -`/review-code` in Step 1 still runs when it applies; Phase 0 of that skill -handles trivial diffs, and acknowledgment-only replies don't need it at all. +Step 1's review still runs on every commit — this carve-out is about the +draft-file step, not the review. Phase 0 is what rules a trivial diff out, and +its Skipped result satisfies the gate. An acknowledgment-only PR reply commits +nothing, so there is no diff to review. **Single-skill gate.** Each of the three subflows above runs `/voice personal` before printing the draft — the full pattern walk covering AI-writing signs, universal good-writing rules, Craig's voice patterns, and the artifact-mechanics patterns (first-person rewrite, public-artifact scope flag, praise/correction asymmetry, finding stems). Publish artifacts (commits, PR titles + bodies, PR review comments) always use personal mode; the `.ai/`-tracking check at the top of Step 2 decides only whether the approval gate fires, not which patterns run. Running the skill is mandatory; the printed draft must have been through it. When the user asks mid-flow for "the voice pass" on an in-progress draft, that means re-run the full pattern walk — not a subset. Always state that the skill ran when announcing the printed draft (e.g. "/voice personal — full pattern walk"). Skipping the pass without flagging it is a defect. The terse/omit-needless-words cut (pattern #38) is the *last* thing the skill does before the draft is printed: read each sentence and cut it in half, keeping only what changes meaning. The draft the user first sees must already be terse — if they have to ask for an Orwell pass after seeing it, the pass was skipped. diff --git a/publish/references/pull-requests.md b/publish/references/pull-requests.md new file mode 100644 index 0000000..9ac4ded --- /dev/null +++ b/publish/references/pull-requests.md @@ -0,0 +1,105 @@ +# Pull requests and PR review comments + +Loaded from the `publish` skill when the artifact is a PR description or a PR +review comment. A plain commit never needs any of this, which is why it lives +here rather than in SKILL.md. + +Steps 0 and 1 of the publish flow (pre-flight reconcile, local code review) and +the `/voice personal` pass still apply — see SKILL.md. This file carries only +what is specific to PRs. + +**For PR descriptions:** + +1. Write the title as line 1 and the body below it to `/tmp/pr-<slug>.md`. **Title format:** the conventional-commit subject (`refactor: remove dead if-count-is-not-None check in admin`). If the project defines a publishing overlay with a ticket system, follow it for the ticket suffix in the title and the cross-link line in the body (see the overlay). +2. Run `/voice personal` on the file. The PR title stays imperative per Conventional Commits — `/voice personal` rewrites the body, not the title. +3. Print the final draft inline in the terminal. Title on line 1, blank line, then body — exactly as it'll be posted. State that the skill ran. Surface any pattern #39 (public-artifact scope) warnings. +4. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default. + - **Approve** → continue to step 5. + - **Request changes** → make them, re-run `/voice personal`, re-print inline, ask again. + - **Open in editor** → only if the user asks. `emacsclient -n /tmp/pr-<ticket-or-slug>.md`. After the editor closes, re-read the file, re-print inline, ask again. +5. Split the file on the first blank line and pass the title and body to `gh pr create --title "..." --body "$(tail -n +3 <file>)"` (or a heredoc) so formatting is preserved. Add `--reviewer <user[,user...]>` in the same call when you already know who should review. +6. Request reviewers on the new PR if you didn't pass `--reviewer` at create time. Use `gh pr edit <N> --add-reviewer <user>`. If the repo has a `CODEOWNERS` file, GitHub auto-suggests based on touched paths. Still issue the explicit request so the reviewer gets notified. Pick reviewers per the team's convention for the area touched (often documented in the per-repo `CLAUDE.md`). For follow-up PRs, consider tagging the parent PR's author if their context would help. PRs without a human reviewer request stall — "checks passed" is not a substitute for review. +7. **Project publishing overlay (if present).** If the project defines a publishing overlay — a `publishing-<team>.md` rule loaded from its `.claude/rules/` — run its post-create steps now: ticket cross-linking, ticket-state moves, and any other tracker integration it specifies. A project with no overlay skips this; the PR is already open and reviewers are requested, which is the complete universal flow. + +**For PR review comments and replies (review verdicts, threaded discussion, follow-up notes on someone else's PR or your own):** + +Pick the shape first. Most reviews are Shape 1. + +- **Shape 1 — Single review** (verdict + summary body + 0+ inline pins). The default for any post that carries a verdict (`APPROVE`, `REQUEST_CHANGES`, `COMMENT`), even when the verdict has no line-specific findings. One `gh api` call posts the summary, every inline pin, and the verdict together. review notification fires once for `APPROVE` or `REQUEST_CHANGES`. +- **Shape 2 — Issue-thread comment** (no verdict). General PR discussion, not a review. No inline pins. No review notification. +- **Shape 3 — Reply on an existing inline thread**. Responding to a specific prior reviewer comment. Threads under that comment. No review notification. + +**Inline threshold for Shape 1.** Any finding that names a `path:line` belongs as an inline comment pinned to that line. Cross-cutting observations (verdict rationale, "third PR with the same pattern", overall test-coverage gaps that don't pin to one place) stay in the summary body. There's no "fold one inline into the summary" exception — a single line-specific finding still goes inline. + +**Shape 1: Single review (bundled summary + inline)** + +1. Identify findings, split into **inline-eligible** (each names a specific `path:line`) and **summary-only** (cross-cutting). Decide the verdict. + +2. Write one concatenated draft to `/tmp/pr-<N>-review.md` with explicit separators: + + ``` + === SUMMARY === + <verdict summary body> + + === INLINE path=frontend/src/foo.tsx line=440 === + <inline body 1> + + === INLINE path=frontend/src/bar.tsx line=137 === + <inline body 2> + ``` + + The separator format is exactly `=== SUMMARY ===` and `=== INLINE path=<path> line=<n> ===`. The summary block is mandatory even for verdict-only reviews. Inline blocks are zero-or-more. + +3. Run `/voice personal` on the file once. The skill walks its full pattern list across every block at the same time. The separators stay intact because they aren't prose. + +4. Print the final draft inline in the terminal. Every block — the summary body AND the full prose of every inline comment — exactly as it'll be posted, with its separator header. Print the inline in full; never describe it in place of printing it ("I'd pair it with one inline on…"). Craig approves the exact words that post under his name, so the exact words must be on screen. State that the skill ran (e.g. "/voice personal — full pattern walk across summary + 3 inline"). Surface any pattern #39 warnings. + +5. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default. + - **Approve** → continue to step 6. + - **Request changes** → make them, re-run `/voice personal` on the whole file, re-print inline, ask again. + - **Open in editor** → only if the user asks. `emacsclient -n /tmp/pr-<N>-review.md`. After the editor closes, re-read, re-print inline, ask again. + +6. Split the file on the separator lines and post in **a single** `gh api` call: + + ``` + gh api repos/<owner>/<repo>/pulls/<N>/reviews \ + --hostname <ghe-host-or-omit> \ + -F event=REQUEST_CHANGES \ + -F body="<summary block>" \ + -F "comments[][path]=<path1>" \ + -F "comments[][line]=<line1>" \ + -F "comments[][body]=<inline 1>" \ + -F "comments[][path]=<path2>" \ + -F "comments[][line]=<line2>" \ + -F "comments[][body]=<inline 2>" + ``` + + `event` is one of `APPROVE`, `REQUEST_CHANGES`, `COMMENT`. The `comments[]` array can be empty for verdicts with zero line-specific findings — the call still uses the same endpoint. Pass `--hostname` for non-`github.com` hosts (a project's publishing overlay names its host when it's a GitHub Enterprise instance). + +7. Verify the review landed. `gh api repos/<owner>/<repo>/pulls/<N>/reviews --hostname ...` returns the latest review with bundled inlines. Confirm `state` matches the verdict and the inline count matches what was posted. + +8. **Project review-notification overlay (if present).** If the project defines a publishing overlay with a review-notification step (e.g. a Slack ping to the PR author), run it now — but only for `APPROVE` and `REQUEST_CHANGES` verdicts. The overlay owns the channel, the message format, the author-mention lookup, and the threading. A project with no overlay skips notification entirely. `COMMENT` verdicts and Shapes 2-3 below never notify, overlay or not. + +**Shape 2: Issue-thread comment (no verdict)** + +Use when the post is informal discussion that shouldn't appear as a review verdict (e.g. "I'd like to discuss the X approach before you continue"). + +1. Write the proposed comment to `/tmp/pr-<N>-comment.md`. +2. Run `/voice personal`. +3. Print inline, ask approve/changes/edit, gate as in Shape 1 step 5. +4. Post: `gh pr comment <N> --body-file /tmp/pr-<N>-comment.md`. +5. Verify: `gh api repos/<owner>/<repo>/issues/<N>/comments`. +6. No review notification. + +**Shape 3: Reply on an existing inline thread** + +Use when responding to a specific prior reviewer comment. + +1. Find the parent comment ID: `gh api repos/<owner>/<repo>/pulls/<N>/comments`. +2. Write the reply to `/tmp/pr-<N>-reply-<comment-id>.md`. +3. Run `/voice personal`. +4. Print inline, ask approve/changes/edit, gate as in Shape 1 step 5. +5. Post: `gh api repos/<owner>/<repo>/pulls/<N>/comments -F in_reply_to=<comment-id> -F body="$(cat /tmp/pr-<N>-reply-<comment-id>.md)"`. +6. Verify in the same `comments` list. +7. No review notification. + diff --git a/review-code/SKILL.md b/review-code/SKILL.md index a2b3c2b..559cee8 100644 --- a/review-code/SKILL.md +++ b/review-code/SKILL.md @@ -33,7 +33,31 @@ When intent context is given, the review grades "does this match what was asked? ## Execution Model -For substantive reviews on large diffs: **dispatch the perspective passes as parallel sub-agents** via the Agent tool. Each sub-agent starts with a clean context window — the reviewer shouldn't inherit the implementer's mental model. For small single-commit tweaks, run inline. +Two levels of dispatch, and conflating them is the mistake to avoid. + +**Level one — who runs this skill.** When invoked from the `publish` flow's Step 1 gate, this skill is already running inside an isolated reviewer subagent that the publish flow spawned. That isolation is not optional and not this skill's call: the author never reviews their own change. If you are reading this in the same context that wrote the diff, the publish flow was not followed. + +**Level two — how the perspectives run inside it.** For substantive reviews on large diffs, dispatch the Phase 2 perspective passes as parallel sub-agents. For small single-commit tweaks, run them inline. This is a cost decision about fan-out *within* the review and never a licence to skip level one. + +### The adversarial contract (publish-flow reviews) + +When running as the publish flow's reviewer, operate under these terms: + +- **You have three inputs, and the boundary is deliberate.** The diff; a one-line claim from the author about what it does; and, when one exists, the requirement source it was built against (ticket, plan, ADR, task body). You were *not* given the conversation, the author's reasoning, or the alternatives they rejected, because those transmit the author's model of the change and your value is in not holding it. Do not ask for them. +- **The requirement source is not leakage — use it.** It was written before the work and usually by someone else, so it is the one input that can contradict the author's claim about their own diff. Without it, the claim is self-certifying and you can only check the diff against a sentence the author wrote. It is what makes the Intent-vs-Delivery criterion below live rather than skipped, and scope creep and missing requirements are exactly what it catches. +- **Review the diff against the claim.** Does it do what the claim says? What does it do that the claim does not mention? What breaks that the claim assumes is fine? +- **Try to refute the change, not to bless it.** Assume there is something wrong and go looking. The default posture is skepticism. +- **A finding you cannot substantiate against the diff is not a finding.** Drop it. An agent told to attack will manufacture findings to satisfy the instruction, and a manufactured finding costs the author a round of work and teaches them to discount the next review. The confidence filter and false-positive filter in Phase 4 are what hold this line: adversarial raises how hard you look, never how weak a claim you will ship. +- **Verify the premise before judging the fix.** When the diff claims to fix a bug, confirm the bug is real and reproduces in the pre-change code. A fix for a misdiagnosed problem passes a diff-shaped review and is still wrong. + +### Re-review mode (continued rounds) + +The publish flow sends the updated diff back to the *same* reviewer rather than spawning a fresh one, so a continued round has your prior findings in context. On each round: + +1. **Re-verify every prior blocking finding against the new diff.** Not against the author's description of the fix. "I fixed it" is a claim like any other, and accepting it is how a re-review becomes a rubber stamp. +2. **Review the fix as a new change.** A fix written under review pressure is prime ground for a regression, so it earns the same scrutiny as the original diff, including on lines the fix touched incidentally. +3. **Say when a prior finding recurs.** If something reported fixed is back, name it as a recurrence rather than filing it fresh. The publish flow treats recurrence as oscillation and stops the loop, which is the right outcome — another round will not converge. +4. **Do not invent new findings to justify another round.** If the blocking findings are addressed and nothing new is substantiated, approve. Approval is the expected end state, not a failure to find something. ## Phase 0 — Eligibility Gate @@ -261,7 +285,7 @@ Do **not** flag any of these as issues: - **Issues explicitly silenced in code** (e.g., `# type: ignore[...]` with a reason, lint ignore comments) unless the silencing is unjustified - **Intentional changes** in functionality clearly related to the PR's stated goal - **Changes in unmodified lines** (real issues in files the PR touches but on lines it doesn't change) -- **Framework behavior being tested** — see `testing.md` anti-patterns +- **Framework behavior being tested** — see the `testing-standards` skill, anti-patterns ### Severity Categorization @@ -437,7 +461,7 @@ None. ## Hand-Off -- **Critical** → must be addressed before merge; author fixes, re-review via `/review-code` on the updated SHA +- **Critical** → must be addressed before merge; author fixes, then the updated diff comes back to *this* reviewer for another round (publish flow, Step 1), not to a fresh one and not to the author's own judgment - **Important** → fix, or deliberately defer with an ADR (run `/arch-decide`) - **Minor** → follow-up issues or a cleanup PR - **Intent-vs-Delivery gaps** → either file tickets for the missing pieces or update the plan to reflect reality diff --git a/scripts/tests/ai-launcher-helper.bats b/scripts/tests/ai-launcher-helper.bats new file mode 100644 index 0000000..0ede4fb --- /dev/null +++ b/scripts/tests/ai-launcher-helper.bats @@ -0,0 +1,328 @@ +#!/usr/bin/env bats +# The ai launcher's --helper flag: open a SECOND agent session in a project that +# already has a live one, under the helper-mode.org role contract. +# +# The load-bearing behavior is the roster gate. `ai --helper` is an assertion by +# the operator that a primary is already running; the roster is what checks it. +# Three outcomes, all tested here: confirmed (launch a helper), refuted (no other +# agent — warn and launch a normal primary instead), and unverifiable (no roster +# script, or a platform without /proc — warn and launch a helper anyway, because +# helper mode is the strictly less destructive guess when we cannot tell). +# +# --print-launch is the seam, as it is for the runtime tests: it prints the exact +# command a real run would send to the pane without touching tmux or fzf. The +# roster runs BEFORE that print, so the printed line reflects the real decision. + +setup() { + REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../.." && pwd)" + AI="$REPO_ROOT/claude-templates/bin/ai" + PROJ="$(mktemp -d)" + mkdir -p "$PROJ/.ai/scripts" + touch "$PROJ/.ai/protocols.org" + # Every tmux call in this file goes to a private server under the test + # tmpdir, so nothing here can reach Craig's live 'ai' session. + export TMUX_TMPDIR="$PROJ" + unset TMUX + # Source for direct access to the pure cores. The guard skips main(). + # shellcheck disable=SC1090 + source "$AI" +} + +teardown() { + tmux kill-server 2>/dev/null || true + rm -rf "$PROJ" +} + +# Install a stub roster that exits with the given status. Exit codes are the +# real agent-roster's contract: 0 alone, 1 others live, 2 unavailable. +_stub_roster() { + cat > "$PROJ/.ai/scripts/agent-roster" <<STUB +#!/bin/bash +exit $1 +STUB + chmod +x "$PROJ/.ai/scripts/agent-roster" +} + +# --- the roster gate, end to end through --print-launch ------------------------ + +@test "--helper with a live primary launches under the helper contract" { + _stub_roster 1 + run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"helper-mode.org"* ]] + # The helper opener replaces the primary one; it must not send the session + # to protocols.org, whose startup would run pulls, rsync, and inbox work. + [[ "$output" != *"protocols.org"* ]] +} + +@test "--helper exports the agent id and the helper flag into the pane" { + _stub_roster 1 + run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"AI_AGENT_ID=helper-"* ]] + [[ "$output" == *"AI_HELPER=1"* ]] +} + +@test "--helper assigns a helper-<rand4> id" { + _stub_roster 1 + run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" =~ AI_AGENT_ID=helper-[0-9a-f]{4}[[:space:]] ]] +} + +@test "--helper honors an id the caller already exported" { + _stub_roster 1 + AI_AGENT_ID=helper-beef run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"AI_AGENT_ID=helper-beef"* ]] +} + +@test "--helper sanitizes an id carrying shell metacharacters" { + _stub_roster 1 + # The id is interpolated into the command typed into the pane. An id + # carrying ';' would end the assignment and run the rest as its own + # command — the helper never launches and something else does. + AI_AGENT_ID='x;touch /tmp/ai-helper-pwned' run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" != *";touch"* ]] + [[ "$output" != *" /tmp/ai-helper-pwned"* ]] + # Assert the exact surviving form too. Negative-only assertions also pass + # when the id is dropped or mangled some other way, which is how a broken + # sanitizer slipped through once already. + [[ "$output" == *"AI_AGENT_ID=x_touch__tmp_ai-helper-pwned "* ]] +} + +@test "--helper sanitizes an id carrying a space" { + _stub_roster 1 + AI_AGENT_ID='helper beef' run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + # A bare space would split the assignment from the command word. Anchored on + # the following space, not a substring: a substring match also accepts a + # mangled "helper_beef_", which an earlier sanitizer actually produced. + [[ "$output" == *"AI_AGENT_ID=helper_beef "* ]] +} + +@test "--helper mints a fresh id rather than reusing a live one" { + _stub_roster 1 + # A helper's pane exports AI_AGENT_ID, so `ai --helper` run from inside a + # helper inherits its parent's id. Reusing it lands both agents on one + # .ai/session-context.d/<id>.org — the lost-update shape helper mode exists + # to prevent. + mkdir -p "$PROJ/.ai/session-context.d" + printf 'helper-beef\n' > "$PROJ/.ai/session-context.d/helper-beef.org" + AI_AGENT_ID=helper-beef run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" != *"AI_AGENT_ID=helper-beef"* ]] + [[ "$output" =~ AI_AGENT_ID=helper-[0-9a-f]{4}[[:space:]] ]] + [[ "$output" == *"already live"* ]] +} + +@test "--helper with no other agent falls back to a primary session and says so" { + _stub_roster 0 + run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + # Refuted: this is the normal primary launch. + [[ "$output" == *"protocols.org"* ]] + [[ "$output" != *"helper-mode.org"* ]] + [[ "$output" != *"AI_HELPER=1"* ]] + [[ "$output" == *"no other agent"* ]] +} + +@test "--helper with no roster installed still launches a helper, with a warning" { + # No stub written: an older checkout whose .ai/scripts predates agent-roster. + run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"helper-mode.org"* ]] + [[ "$output" == *"could not verify"* ]] +} + +@test "--helper with an unavailable roster still launches a helper, with a warning" { + _stub_roster 2 + run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"helper-mode.org"* ]] + [[ "$output" == *"could not verify"* ]] +} + +@test "--helper names the host and project in the opener, as the primary does" { + _stub_roster 1 + run bash "$AI" --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"$(basename "$PROJ")"* ]] + [[ "$output" == *"$(uname -n)"* ]] +} + +@test "--helper composes with --runtime" { + _stub_roster 1 + run bash "$AI" --runtime codex --helper --print-launch "$PROJ" + [ "$status" -eq 0 ] + [[ "$output" == *"codex "* ]] + [[ "$output" == *"helper-mode.org"* ]] +} + +@test "--helper refuses a directory that is not an agent-template project" { + run bash "$AI" --helper --print-launch "$BATS_TEST_TMPDIR" + [ "$status" -eq 1 ] + [[ "$output" == *"protocols.org"* ]] +} + +@test "--helper needs a project directory" { + run bash "$AI" --helper + [ "$status" -eq 2 ] + [[ "$output" == *"needs a project directory"* ]] +} + +# --- pure cores --------------------------------------------------------------- + +@test "_helper_launch_mode: roster found other agents (1) — launch a helper" { + run _helper_launch_mode 1 + [ "$output" = helper ] +} + +@test "_helper_launch_mode: roster says alone (0) — fall back to primary" { + run _helper_launch_mode 0 + [ "$output" = primary ] +} + +@test "_helper_launch_mode: roster unavailable (2) — helper, unverified" { + run _helper_launch_mode 2 + [ "$output" = helper-unverified ] +} + +@test "_helper_launch_mode: no roster script at all — helper, unverified" { + run _helper_launch_mode absent + [ "$output" = helper-unverified ] +} + +@test "_resolve_helper_launch: builds the roster path from its own argument" { + _stub_roster 1 + # With no `dir` in the caller's scope, a roster path built from the caller's + # variable instead of the parameter resolves to "/.ai/scripts/agent-roster", + # which isn't executable — so the gate would silently report unverified and + # every helper launch would skip its check. The bug is invisible when the + # caller happens to have its own $dir holding the same value, which both + # production callers do. + unset dir + run _resolve_helper_launch "$PROJ" + [ "$output" = helper ] +} + +@test "_helper_id: shape is helper- plus four hex digits" { + run _helper_id + [[ "$output" =~ ^helper-[0-9a-f]{4}$ ]] +} + +@test "_helper_id: uses the full 16 bits, not bash RANDOM's 15" { + # The shape test alone passes against `RANDOM % 65536`, which can never set + # the top bit — so every id would begin 0-7 and nothing would fail. Draw + # enough to make a genuinely 16-bit generator almost certain to show a high + # leading digit, and assert one appears. + local i high=0 + for i in $(seq 1 200); do + case "$(_helper_id)" in + helper-[89abcdef]*) high=1; break ;; + esac + done + [ "$high" -eq 1 ] +} + +@test "_sanitize_agent_id: keeps the safe charset and maps everything else" { + run _sanitize_agent_id 'helper-a83f' + [ "$output" = "helper-a83f" ] + run _sanitize_agent_id 'a b;c/d$e' + [ "$output" = "a_b_c_d_e" ] + run _sanitize_agent_id 'keep.dots_and-dashes' + [ "$output" = "keep.dots_and-dashes" ] +} + +@test "_resolve_helper_id: a minted id also avoids a live anchor" { + # Seed every id _helper_id can produce for a stubbed generator, so the mint + # path must notice the collision rather than hand back a taken id. + mkdir -p "$PROJ/.ai/session-context.d" + _helper_id() { echo "helper-dead"; } + : > "$PROJ/.ai/session-context.d/helper-dead.org" + run _resolve_helper_id "$PROJ" + # Bounded retries mean it gives up and returns the id, but it must not have + # returned it silently on the first look — the loop ran its full bound. + [ "$status" -eq 0 ] + [ "$output" = "helper-dead" ] +} + +@test "_resolve_helper_id: a free minted id is returned as-is" { + _helper_id() { echo "helper-cafe"; } + run _resolve_helper_id "$PROJ" + [ "$output" = "helper-cafe" ] +} + +# --- window ordering ---------------------------------------------------------- + +@test "_order_windows: a helper window sorts with its project, not with others" { + local listing names out + listing="$(printf 'beta\t@1\nzzz-other\t@2\nalpha:helper-a83f\t@3\nalpha\t@4')" + names="$(printf 'alpha\nbeta')" + out="$(printf '%s\n' "$listing" | _order_windows "$names" | cut -f1 | paste -sd, -)" + [ "$out" = "zzz-other,alpha,alpha:helper-a83f,beta" ] +} + +@test "_order_windows: a colon name whose prefix is not a project stays in others" { + local out + out="$(printf 'nope:helper-a83f\t@1\n' | _order_windows "$(printf 'alpha')" | cut -f1)" + [ "$out" = "nope:helper-a83f" ] +} + +# --- functional: the second window (private tmux socket) ---------------------- +# +# The regression these guard against: single_mode focuses the project's existing +# window and returns, so routing a helper through it would hand back the PRIMARY +# session instead of opening a second one. +# +# The window-list tail (sort_windows, attach_session) is stubbed out. Both are +# already covered in the characterization suite, attaching needs a real terminal +# these tests don't have, and build_candidates legitimately returns non-zero +# under bats's errexit (bin/ai itself runs without set -e — see that file's NOTE). +_stub_window_tail() { + sort_windows() { :; } + attach_session() { :; } + export AGENT_CMD="true" +} + +@test "functional helper_mode: opens a NEW window beside the project's existing one" { + _stub_roster 1 + _stub_window_tail + tmux new-session -d -s ai -n "$(basename "$PROJ")" -c "$PROJ" + run helper_mode "$PROJ" + [ "$status" -eq 0 ] + names="$(tmux list-windows -t ai -F '#{window_name}')" + # The primary's window survives untouched, and a helper window joins it. + printf '%s\n' "$names" | grep -qx "$(basename "$PROJ")" + printf '%s\n' "$names" | grep -qE "^$(basename "$PROJ"):helper-[0-9a-f]{4}$" + [ "$(printf '%s\n' "$names" | wc -l)" -eq 2 ] +} + +@test "functional helper_mode: the window name carries the exported id" { + _stub_roster 1 + _stub_window_tail + tmux new-session -d -s ai -n base -c "$PROJ" + AI_AGENT_ID=helper-beef run helper_mode "$PROJ" + [ "$status" -eq 0 ] + tmux list-windows -t ai -F '#{window_name}' | grep -qx "$(basename "$PROJ"):helper-beef" +} + +@test "functional helper_mode: an empty roster opens the plain project window" { + _stub_roster 0 + _stub_window_tail + tmux new-session -d -s ai -n base -c "$PROJ" + run helper_mode "$PROJ" + [ "$status" -eq 0 ] + names="$(tmux list-windows -t ai -F '#{window_name}')" + printf '%s\n' "$names" | grep -qx "$(basename "$PROJ")" + ! printf '%s\n' "$names" | grep -q ':helper-' +} + +# --- help --------------------------------------------------------------------- + +@test "usage documents --helper" { + run bash "$AI" -h + [ "$status" -eq 0 ] + [[ "$output" == *"--helper"* ]] +} diff --git a/testing-standards/SKILL.md b/testing-standards/SKILL.md new file mode 100644 index 0000000..1f16528 --- /dev/null +++ b/testing-standards/SKILL.md @@ -0,0 +1,391 @@ +--- +name: testing-standards +description: | + The full testing standard: characterization tests for untested legacy code, the Normal/Boundary/Error case detail, combinatorial and property-based and mutation testing, test organization and the pyramid, integration-test rules, naming conventions, test-quality rules (independence, determinism, performance, mocking boundaries, signs of overmocking, testing framework-heavy code, never inlining production code, asserting error behavior not error text), the refactor-when-tests-are-hard principle, coverage targets, the TDD discipline table, the spike exception, and the anti-pattern list. + + Use when writing or reviewing tests, deciding how to test something, hardening untested code, or judging whether a test suite is adequate. + + Do NOT use for the standing directive itself — that TDD is the default and that every unit needs Normal, Boundary, and Error cases lives in claude-rules/testing.md and is always loaded. Also see the add-tests skill for the guided coverage workflow and pairwise-tests for the combinatorial matrix generator. +--- + +# Testing Standards — the detail + +Applies to test code and to decisions about how to test. + +The standing directive is NOT here. That TDD is the default, and that every +unit needs Normal, Boundary, and Error cases, lives in `claude-rules/testing.md` +and is always loaded, because it has to fire before any code gets written and +nothing else would summon it. This file is everything needed once you are +actually writing the tests. + +### Understand Before You Test + +Before writing tests, invest time in understanding the code: + +1. **Explore the codebase** — Read the module under test, its callers, and its dependencies. Understand the data flow end to end. +2. **Identify the root cause** — If fixing a bug, trace the problem to its origin. Don't test (or fix) surface symptoms when the real issue is deeper in the call chain. +3. **Reason through edge cases** — Consider boundary conditions, error states, concurrent access, and interactions with adjacent modules. Your tests should cover what could actually go wrong, not just the obvious happy path. + +### Adding Tests to Existing Untested Code + +When working in a codebase without tests: + +1. Write a **characterization test** that captures current behavior before making changes +2. Use the characterization test as a safety net while refactoring +3. Then follow normal TDD for the new change + +A characterization test asserts what the code *actually does* right now, not +what it *should* do. Write it by running the code against a fixed input, +reading the exact value or effect it currently produces, and asserting that +value — Feathers' recipe is to assert something you know is wrong, run it, and +paste the real value out of the failure. You don't need to know the correct +answer to write one; you record the observed one. That's what makes it +mechanical enough to bring a large untested surface under test without +re-deriving each unit's spec. + +**Characterize with the same Normal/Boundary/Error set as any unit** (the three +categories below), not one happy-path capture per function. On a characterization +test the negative and boundary cases are the ones that find bugs: untested legacy +code is weakest exactly at the empty input, the malformed value, the missing +upstream, and pinning what it *currently* does there writes the wrong behavior +down in black and white, where it becomes a bug you can see and decide on. When a +pinned case turns out to be a bug rather than behavior worth preserving, that one +test graduates from "record current" to "assert correct" and you fix the code. +The happy-path case is the regression net; the negative and boundary cases are +the audit. + +Bugs that live *inside* a unit are caught by this three-category set; bugs in how +units compose — ordering, shared state handed between them — are invisible to any +per-unit test and need a functional/integration test over the composed path (see +Integration Tests below and the pyramid). + +### 1. Normal Cases (Happy Path) +- Standard inputs and expected use cases +- Common workflows and default configurations +- Typical data volumes + +### 2. Boundary Cases +- Minimum/maximum values (0, 1, -1, MAX_INT) +- Empty vs null vs undefined (language-appropriate) +- Single-element collections +- Unicode and internationalization (emoji, RTL text, combining characters) +- Very long strings, deeply nested structures +- Timezone boundaries (midnight, DST transitions) +- Date edge cases (leap years, month boundaries) + +### 3. Error Cases +- Invalid inputs and type mismatches +- Network failures and timeouts +- Missing required parameters +- Permission denied scenarios +- Resource exhaustion +- Malformed data + +## Combinatorial Coverage + +For functions with 3+ parameters that each take multiple values (feature-flag +combinations, config matrices, permission/role interactions, multi-field +form validation, API parameter spaces), the exhaustive test count explodes +(M^N) while 3-5 ad-hoc cases miss pair interactions. Use **pairwise / +combinatorial testing** — generate a minimal matrix that hits every 2-way +combination of parameter values. Empirically catches 60-90% of combinatorial +bugs with 80-99% fewer tests. + +Invoke `/pairwise-tests` on the offending function; continue using `/add-tests` +and the Normal/Boundary/Error discipline for the rest. The two approaches +complement: pairwise covers parameter *interactions*; category discipline +covers each parameter's individual edge space. + +Skip pairwise when: the function has 1-2 parameters (just write the cases), +the context requires *provably* exhaustive coverage (regulated systems — document +in an ADR), or the testing target is non-parametric (single happy path, +performance regression, a specific error). + +## Escalation Beyond Category and Pairwise + +The Normal/Boundary/Error categories and the pairwise matrix are the default +discipline. Two further techniques escalate beyond them — reach for them when +the default leaves a gap, not on every unit. + +### Property-Based Testing + +When an invariant holds across a broad input domain — round-trips +(`decode(encode(x)) == x`), idempotence (`f(f(x)) == f(x)`), ordering +invariants (output is always sorted), or any "output always satisfies X" — +generate inputs and assert the property instead of enumerating cases. The +generator explores corners you wouldn't think to write by hand, and a +failing case shrinks to a minimal reproducer. Use the standard tool for the +language (Hypothesis for Python, fast-check for JS, proptest for Rust). +State the property as the test name and let the framework supply the inputs. + +Reach for this when the behavior is a law over a domain rather than a fixed +set of examples. Keep category-discipline cases for the specific edges that +must always hold; the property test covers the space between them. + +### Mutation Testing + +When line coverage is high but you suspect the assertions are thin — tests +that execute the code without checking its output, or that pass with a +function body replaced by a stub — use mutation testing to measure whether +the suite actually kills injected faults. The tool flips conditionals, swaps +operators, and deletes statements, then reruns the suite; a surviving mutant +is a fault the tests didn't catch. Use mutmut or cosmic-ray for Python, +Stryker for JS. High line coverage with a low mutation score means weak +assertions, not a tested codebase. + +Reach for this on critical logic where coverage looks reassuring but you +want evidence the tests would fail on a regression. It's a diagnostic, not a +gate on every change — mutation runs are slow. + +## Test Organization + +Typical layout: + +``` +tests/ + unit/ # One test file per source file + integration/ # Multi-component workflows + e2e/ # Full system tests +``` + +Per-language files may adjust this (e.g. Elisp collates ERT tests into +`tests/test-<module>*.el` without subdirectories). + +### Testing Pyramid + +Rough proportions for most projects: +- Unit tests: 70-80% (fast, isolated, granular) +- Integration tests: 15-25% (component interactions, real dependencies) +- E2E tests: 5-10% (full system, slowest) + +Don't duplicate coverage: if unit tests fully exercise a function's logic, +integration tests should focus on *how* components interact — not repeat the +function's case coverage. + +## Integration Tests + +Integration tests exercise multiple components together. Two rules: + +**The docstring names every component integrated** and marks which are real vs +mocked. Integration failures are harder to pinpoint than unit failures; +enumerating the participants up front tells you where to start looking. + +Example: + +``` +def test_integration_refund_during_sync_updates_ledger_atomically(): + """Refund processed mid-sync updates order and ledger in one transaction. + + Components integrated: + - OrderService.refund (entry point) + - PaymentGateway.reverse (MOCKED — returns success) + - Ledger.credit (real) + - db.transaction (real) + + Validates: + - Refund rolls back if ledger write fails + - Both tables updated or neither + """ +``` + +**Write an integration test when** multiple components must work together, +state crosses function boundaries, or edge cases combine. **Don't** when +single-function behavior suffices, or when mocking would erase the interaction +you meant to test. + +## Naming Convention + +- Unit: `test_<module>_<function>_<scenario>_<expected>` +- Integration: `test_integration_<workflow>_<scenario>_<outcome>` + +Examples: +- `test_cart_apply_discount_expired_coupon_raises_error` +- `test_integration_order_sync_network_timeout_retries_three_times` + +Languages that prefer camelCase, kebab-case, or other conventions keep the +structure but use their idiom. Consistency within a project matters more than +the specific case choice. + +## Test Quality + +### Independence +- No shared mutable state between tests +- Each test runs successfully in isolation +- Explicit setup and teardown + +### Determinism +- Never hardcode dates or times — generate them relative to `now()` +- No reliance on test execution order +- No flaky network calls in unit tests +- Time/clock-mocking helpers must avoid two recurring failure modes: + - *Infinite recursion.* The helper must not call the primitive it's + replacing. If the mock for `now()` calls `now()`, the test stack + overflows. Compute the mock value from a fixed source (a captured + instant, an injected fake clock). + - *Scope-shadowing without reach.* A mock that only exists inside + the test function won't affect production code that reads the + symbol through its canonical path. Replace the symbol at its + definition site (monkey-patch the module attribute in Python, + redefine the global in Lisp, swap the package-level binding in + Go, replace the named export in JavaScript) — or inject a fake + via dependency-inversion. Don't lean on scope-shadowing + primitives (Lisp `let`, Python local rebind, JS shadowed `let`) + that fence the mock to the test's lexical scope; production code + won't see them and the test passes against the real clock. + +### Performance +- Unit tests: <100ms each +- Integration tests: <1s each +- E2E tests: <10s each +- Mark slow tests with appropriate decorators/tags + +### Mocking Boundaries +Mock external dependencies at the system boundary: +- Network calls (HTTP, gRPC, WebSocket) +- File I/O and cloud storage +- Time and dates +- Third-party service clients + +Never mock: +- The code under test +- Internal domain logic +- Framework behavior (ORM queries, middleware, hooks, buffer primitives) + +### Signs of Overmocking + +Ask yourself: + +- Would this test still pass if I replaced the function body with `raise NotImplementedError` (or equivalent)? If yes, the mocks are doing the work — you're testing mocks, not code. +- Is the mock more complex than the function being tested? Smell. +- Am I mocking internal string / parsing / decoding helpers? Those aren't boundaries — they're the work. +- Does the test break when I refactor without changing behavior? Good tests survive refactors; overmocked ones couple to implementation. + +When tests demand heavy internal mocking, the fix isn't better mocks — it's +restructuring the code (see *If Tests Are Hard to Write* below). + +### Testing Code That Uses Frameworks + +When a function mostly delegates to framework or library code, test *your* +integration logic: +- ✓ "I call the library with the right arguments in the right context" +- ✓ "I handle its return value correctly" +- ✗ "The library works in 50 scenarios" — trust it; it has its own tests + +For polyglot behavior (e.g., comment handling across C/Java/Go/JS), test 2-3 +representative modes thoroughly plus a minimal smoke test in the others. +Exhaustive permutations are diminishing returns. + +### Test Real Code, Not Copies + +Never inline or copy production code into test files. Always `require`/`import` +the module under test. Copied code passes even when production breaks — the +bug hides behind the duplicate. + +Mock dependencies at their boundary; exercise the real function body. + +### Error Behavior, Not Error Text + +Test that errors occur with the right type; don't assert exact wording: +- ✓ Right exception type (`pytest.raises(ValueError)`, `(should-error ... :type 'user-error)`) +- ✓ Regex on values the message *must* contain (e.g., the offending filename) +- ✗ `assert str(e) == "File 'foo' not found"` — breaks when prose changes even though behavior is unchanged + +Production code should emit clear, contextual errors. Tests verify the +behavior (raised, caught, returned nil) and values that must appear — not the +prose. + +## If Tests Are Hard to Write, Refactor the Code + +If a test needs extensive mocking of internal helpers, elaborate fixture +scaffolding, or mocks that recreate the function's own logic, the production +code needs restructuring — not the test. + +Signals: +- Deep nesting (callbacks inside callbacks) +- Long functions doing multiple things ("fetch AND parse AND decode AND save") +- Tests that mock internal string / parsing / I/O helpers +- Tests that break on refactors with no behavior change + +Fix: extract focused helpers (one responsibility each), test each in isolation +with real inputs, compose them in a thin outer function. Several small unit +tests plus one composition test beats one monster test behind a wall of mocks. + +When the untestable function is legacy code you're hardening, this extraction +**is** the hardening — not a detour around it. A function whose boundary or +error case can't be exercised without mocking the world (a shell function that +calls `tmux`/`git` directly, a handler that reaches straight into I/O) can't be +characterized, so you can't refactor it safely and you can't pin its edge +behavior. Extracting the pure decision logic into a helper that takes plain +inputs and returns a plain result makes that logic characterizable with the full +Normal/Boundary/Error set; the I/O calls become a thin wrapper you cover once +with a single composition test. "It needs too much mocking to test" is therefore +never a reason to skip the boundary and error cases — it's the signal to reshape +the function so those cases are writable. + +## Coverage Targets + +- Business logic and domain services: **90%+** +- API endpoints and views: **80%+** +- UI components: **70%+** +- Utilities and helpers: **90%+** +- Overall project minimum: **80%+** + +New code must not decrease coverage. PRs that lower coverage require justification. + +## TDD Discipline + +TDD is non-negotiable. These are the rationalizations agents use to skip it — don't fall for them: + +| Excuse | Why It's Wrong | +|--------|----------------| +| "This is too simple to need a test" | Simple code breaks too. The test takes 30 seconds. Write it. | +| "I'll add tests after the implementation" | You won't, and even if you do, they'll test what you wrote rather than what was needed. Test-after validates implementation, not behavior. | +| "Let me just get it working first" | That's not TDD. If you can't write a failing test, you don't understand the requirement yet. | +| "This is just a refactor" | Refactors without tests are guesses. Write a characterization test first, then refactor while it stays green. | +| "I'm only changing one line" | One-line changes cause production outages. Write a test that covers the line you're changing. | +| "The existing code has no tests" | Start with a characterization test. Don't make the problem worse. | +| "This is demo/prototype code" | Demos build habits. Untested demo code becomes untested production code. | +| "I need to spike first" | Spikes are fine — under the protocol below. Throw the spike away, then write the first failing test before productionizing. | + +If you catch yourself thinking any of these, stop and write the test. + +### The Spike Exception (Disciplined) + +TDD stays the default. The one sanctioned way to write code before a test is +a spike — exploratory code that answers "is this approach even viable?" when +you can't yet write a meaningful failing test because the shape of the +solution is unknown. A spike is disciplined only when all three hold: + +1. **Timebox it.** Set a limit before starting (an hour, an afternoon) and + stop when it's up. An open-ended spike is just untested implementation + wearing a different name. +2. **Do not commit spike code.** The spike is a learning artifact, not a + deliverable. It never enters the branch history. Keep it in a scratch + file or a throwaway worktree. +3. **Throw the spike away, then start with a failing test.** Once the spike + has answered the viability question, delete it. Write the first failing + test against the now-understood behavior, then productionize under normal + Red/Green/Refactor. The production code is written test-first even though + the exploration wasn't — you don't promote the spike into production by + bolting tests on after. + +The spike buys understanding, not code. If you find yourself keeping the +spike because rewriting it feels wasteful, the timebox was too long or the +problem was tractable enough to TDD from the start. + +## Anti-Patterns (Do Not Do) + +- Hardcoded dates or timestamps (they rot) +- Testing implementation details instead of behavior +- Mocking the thing you're testing +- Mocking internal helpers (string ops, parsing, decoding) — those are the work +- Inlining production code into test files — always `require` / `import` the real module +- Asserting exact error-message text instead of type + key values +- Shared mutable state between tests +- Non-deterministic tests (random without seed, network in unit tests) +- Testing framework behavior instead of your code +- Ignoring or skipping failing tests without a tracking issue + +## Content scope + +Test code, fixtures, docstrings, and comments are checked into the repo and visible to the team. They must follow the *Content scope for public artifacts* rule in [`commits.md`](commits.md): no local paths, no private repo names, no personal tooling references. @@ -39,6 +39,217 @@ Tags are assigned and refreshed by =task-audit=; =task-review= keeps them honest * Rulesets Open Work +** TODO [#B] Voice pattern #48 — corrective antithesis :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-07-31 +:END: +Work proposed a new voice pattern for the corrective form of antithesis: "X +rather than Y", "not X but Y", "X, not Y". Distinct from #9, which catches the +additive form ("not only X but Y"). My ruling, quoted in the handoff: I don't +mind it occasionally, but it has to be for emphasis and it can't be overused. +So it's a frequency rule, not a ban. Proposed cap: about one per 150 words, +never twice in adjacent sentences, mode tags prose + personal. + +Evidence is strong. A four-sentence Slack draft fired it four times in a +hundred words, and I noticed it across messages, which is the tell that it had +stopped being a device. + +Two additions I'd make before applying: + +1. Put it straight into the attestation high-recurrence set. That set is for + patterns with documented failure history, and this one arrived with its + failure history attached. + +2. The frequency rule needs a home outside the voice skill. I noticed this in + conversation, and the skill only runs on publish artifacts, so as proposed + it can't touch the surface where the complaint originated. Mirroring the cap + into =interaction.md= (always loaded) is what would make it bite in chat. + That second half is the part worth deciding on. + +Per the paired-files rule, any change lands in both =voice/SKILL.md= and +=voice/references/voice-profile.org=. The handoff already names what the profile +entry wants: problem statement, the verbatim ruling, the four-in-one-draft +before/after, and a note that #9 is adjacent-but-different so the two don't get +merged. + +Source: inbox/2026-07-31-1312-from-work-new-voice-pattern-proposal-48.org + +*** 2026-07-31 Fri @ 13:32:00 -0500 Craig approved the interaction.md mirror +So the open half of this task is settled and the work is now fully specified. +Both homes get the rule, with a cross-reference line in each so an edit to one +prompts a look at the other. Work argued the duplication is right here because +the two fire on different surfaces and neither subsumes the other, and I agree: +a single home leaves one surface uncovered. + +Placement: a short subsection under =interaction.md='s existing chat-output +rules, beside "No Reverse-Video Highlighting in Chat Output". Those rules +constrain how the agent writes to Craig rather than what it decides, which is +the same shape. + +Work sent suggested text for both files. It needs the em-dashes stripped before +it lands, since it uses them freely while describing a rule that ships into a +zero-tolerance context. + +Remaining work: the =voice/SKILL.md= rule line, the paired +=voice/references/voice-profile.org= entry, the =interaction.md= subsection, the +two cross-reference lines, and adding #48 to the attestation high-recurrence set. + +Source: inbox/2026-07-31-1328-from-work-craig-approved-mirroring-the-48.org + +** DOING [#B] Hostile subagent review before every agent commit :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-07-28 +:END: +From the roam inbox, 2026-07-28: "code reviews must occur before every commit an agent does, and they should be hostile reviews from a subagent without the agent's context." + +Two asks, and only the second is new. The publish flow already mandates a review before every commit (Step 1). What changes is *who reviews*: today the reviewing agent is the one that wrote the change, so it inherits the author's mental model, and =review-code= only *suggests* subagent dispatch, and only "for substantive reviews on large diffs". + +Decisions settled with Craig, 2026-07-28, and shipped: +- *Scope* — every commit. The reviewer's own Phase 0 rules a diff trivial and returns Skipped, which satisfies the gate; the author never rules on their own diff. +- *Stance* — "adversarial", not "hostile" (Craig's call). An agent told to attack manufactures findings, so the stance carries a substantiation floor: a finding not substantiated against the diff is dropped. +- *What the reviewer gets* — the diff, a one-line claim of what it does, and the requirement source (ticket, plan, task body) where one exists. Withheld: the conversation, the exploration, the author's rationale. The requirement source stays *in* because it is the only artifact that can contradict the author's claim; withholding it makes the claim self-certifying. +- *Loop* — re-review until the reviewer approves, turning on blocking findings rather than the verdict token. Bounded at three rounds, and stopped early on a finding that recurs after being reported fixed. Both bounds hand the decision to Craig; the unattended callers park instead. +- *Adjudication* — Craig, never the author overruling the reviewer. +- *Home* — the =publish= skill Step 1, with =review-code= carrying the adversarial contract and re-review mode. +- *The =subagents.md= tension* — resolved with an Isolation Override section: the size heuristics assume the main thread could do the task equally well, and they lapse when its own context is what makes its answer untrustworthy. + +Remaining: nothing on the design. The change shipped in this session. + +** TODO [#B] wrap-org-table splits logical rows, and lint drives it :bug: +:PROPERTIES: +:LAST_REVIEWED: 2026-07-29 +:END: +Reported by work 2026-07-28 against =arch-00-deepsat-platform-spec-draft.org=. Reproduced here. + +*** Verified + +Each of these is a measurement, re-run under adversarial review. The analysis I built on top of them was wrong three times, so this section is deliberately separated from the open questions below. + +- *The defect.* =wrap-org-table.el= turns one logical table row into two or more, by writing a rule between its continuation lines. Content survives; structure does not. +- *Root cause.* =wot--continuation-group-p= (=wrap-org-table.el:168=) requires every line past the first to carry at least one empty cell. When a row overflows in every column its continuation line is fully populated, the predicate rejects the group, and =wot--logical-rows= appends each physical line as its own row (=:197=). +- *Controlled A/B.* Rules present in both, continuation line's middle cell the only variable: blank merges, populated splits. +- *Idempotence is broken.* Running the tool twice on its own correct output corrupts it. Pass 1 emits a properly rule-delimited three-line row; pass 2 splits it into three rows. The docstring at =:203-204= asserts the opposite, and =wot-reformat-is-idempotent= passes because its fixture overflows only one column. +- *lint doesn't just miss it, it causes it.* =lint-org.el:424= calls the same predicate. Given the tool's own correct output — a rule after every logical row — lint reports "missing rule between rows — wrap-org-table.el reflows it". Nothing is missing. Follow that advice and the tool splits the row; lint then reports the result 0 mechanical, 0 judgment. Control: a conformant table whose continuation keeps an empty cell returns 0 and 0. So the loop is not two independent green lights, it is the linter manufacturing a false violation and certifying the damage it caused. +- *A second path.* With no hlines at all, =wot--logical-rows= short-circuits (=:184=) before the predicate is reached, so every physical line becomes a row. +- *Nothing invokes the tool unattended.* =todo-cleanup.el= names it in comments only; the entry-script guard from the 2026-07-09 incident holds. +- *rulesets is exposed*: =todo.org= carries a four-row attachment-sanitization table with no rules between rows. Don't reflow it until the tool is fixed — reflowing is the trigger. + +*** Two fixes that were verified to work + +- *Conformant round-trip.* Replacing the predicate body with =(> (length group) 1)= — pure rule-delimited grouping, no emitter marker, no new field — makes the corrupting pass-1 output round-trip cleanly. +- *Telling a continuation group from two real rows at runtime.* Provenance isn't available (=wot-reformat-table-string= receives a string), but the test is cheap: merge the group, re-wrap at the allocated widths, compare to the group as given. A continuation group reproduces itself under merge-then-wrap; two genuinely distinct short rows don't, because merged they fit on one line. + +Start with a red test from the double-run repro — it needs no unusual input and falsifies the docstring and the passing idempotence test together. Emission is already correct (=:222-224= emits one rule per element of =rows=), so the repair is entirely in how =rows= is computed. + +*Prefer the round-trip check to any detector.* work implemented the predicate-based detection I recommended and demonstrated it cannot discriminate at any threshold (2026-07-29, worked examples from their repo). Run bare it flags 144 files — essentially every table — because an ordinary header-plus-body table is one multi-line fully-populated group and rejecting it is the predicate working correctly. Add a per-row-ruled precondition and it cuts to 9, but at 9 it still mixes a genuinely wrapped row (=arch-09:40=, a header row whose second line continues the sentence) with two distinct rows legitimately sharing a rule (their =todo.org:117=, where splitting is the *right* answer). Same structural signature, opposite correct verdicts. The difference is whether one line continues the other as prose, which is semantics and not in the parse. + +So =lint-org.el:424= cannot simply inherit the repair, and a checker keyed on the predicate would train people to ignore it. The idempotence property is the checkable one: reflow twice and diff. It sidesteps detection entirely, because round-tripping the tool's own output correctly is true by construction and needs nobody to decide what a group means. + +*** Open questions + +- *What should no-hline input do?* My "refuse to reflow" instruction was wrong: adding rules to a ruleless table is the tool's main job, and =test-wrap-org-table.el:147= asserts exactly that. The real danger is narrower — a no-hline table where some line carries an empty cell, so a physical line might be a continuation. Needs a decision on refuse, ask, or heuristic. +- *Which path bit work?* One question settles it: did the =arch-00= Document Status table have rules between its rows before the reflow? I inferred "probably secondary" from a file-level scan, which can't resolve a table-level incident. +- *How exposed is work?* Partly resolved by their own implementation, 2026-07-29. *Four secondary-path files are exact.* The primary-path number is 9 under a per-row-ruled precondition, which they correctly label a floor on a population they cannot cleanly define rather than a measurement — the precondition also drops the minimal =a_full= fixture, which has only two groups. My earlier "24 secondary-path files" certification was not sound: their original signature also matches every correctly-reflowed table, so it never partitioned. +- *Does the grade go up?* Currently Major x most users frequently = P2 = [#B] (any table you reflow that overflows every column, which is what a width violation sends you to the tool to fix). The lint-drives-it finding arrived after that grading and may lift it. + +*** Provenance + +work reverted their table and left it over-budget at 134 columns, correctly: an over-wide table is cosmetic, a table that says something else is not. I hit this same failure on 2026-07-27, wrote "reflowed a table into a worse shape and lint-org then passed it" into a session summary, and never filed it — which is why work met it three weeks later. Their framing beats the apology: a correct observation recorded and then read as fine is the same failure as a green check on a corrupted table. + +Process note for whoever picks this up. This task bounded out of its review loop at three rounds. Every finding across all three landed on inference, never on a measurement — the reproductions held throughout while the reasoning built on them was refuted repeatedly. Trust the Verified section; re-derive anything else. + + +** TODO [#B] Synced workflows link outside the synced set with ../../ :bug: +:PROPERTIES: +:LAST_REVIEWED: 2026-07-28 +:END: +Seven link sites across four synced workflows, three distinct targets, all escaping the =.ai/= boundary into rulesets repo-root paths. From a consuming project's =.ai/workflows/=, =../../= is that project's root, where none of these exist: + +- → =../../claude-rules/todo-format.md= (five sites): =open-tasks.org:163=, =task-audit.org:84=, =task-review.org:60=, =task-review.org:64=, =task-review.org:99= +- → =../../docs/design/task-review.org= (one site): =task-review.org:11= +- → =../../flush/SKILL.md= (one site): =suspend.org:22= + +Verified dead in both home and =.emacs.d=; they resolve only in rulesets, which is why nobody noticed. + +Grading: Minor severity (a documented reference an agent can't follow, workaround is to search) x every user every time (every consuming project, every sync) = P2 = [#B]. Same grade as the =references/= link this came from, and the same mechanism — a synced file linking a path the sync doesn't deliver — with seven sites instead of one. + +Fix direction, two halves. Rewrite the seven as prose references naming the file, the same move taken for the credential paths: a link that resolves in one repo shouldn't be a link in a file that ships to two dozen. Then close the gate, or the eighth arrives unnoticed. + +The gate already exists and is nearly right. =scripts/lint.sh='s =check_md_links= was written for this exact class — its comment says so ("Validate cross-references to =claude-rules/= — the install-layout problem"). It misses these for two concrete reasons: it matches only markdown link syntax (=grep -oE '\[[^]]*\]\([^)]+\)'=), so org =[[file:...]]= links are invisible to it, and its driver loop only feeds it =claude-rules/*.md= and the language rule files, never =.ai/workflows/*.org=. Extending it on both axes is a smaller and more durable fix than a manual sweep. + +Found by the adversarial reviewer on the =references/= fix, 2026-07-28, as the sibling class the original report missed. + +** TODO [#C] start-work Phase 7 still summarizes the old publish flow :chore:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-07-28 +:END: +=.claude/commands/start-work.md:336-339= hands off with "Follow =commits.md= exactly" and "Run =/review-code --staged= before each commit" — no isolated reviewer, no re-review loop. It was already stale before the 2026-07-28 review change, because =commits.md= moved the publish flow into the =publish= skill in an earlier commit, so the pointer names a file that no longer holds the flow. + +Grading: Cosmetic severity (a stale summary beside a correct canonical, and start-work is attended so the escalation target exists) x most users frequently = P3 = [#C]. + +Fix is to point Phase 7 at the =publish= skill rather than restate the flow, which is what let it drift in the first place. Worth a sweep for other files that restate the flow instead of pointing at it. + +Found by the adversarial reviewer during the 2026-07-28 review-flow change, and correctly filed rather than fixed there: the line was untouched by that diff. + +** TODO [#C] Two lint defects at the template source :chore: +:PROPERTIES: +:LAST_REVIEWED: 2026-07-28 +:END: +Both verified at the rulesets source, so every project seeded from them inherits the defect. + +=retrospectives/PRINCIPLES.org:38= violates the org-table standard (no closing rule). =lint-org= flags it as =org-table-standard=, and =wrap-org-table.el= reflows it mechanically. This half is purely tool-driven. + +=protocols.org= lints at 8 mechanical + 19 judgment =misplaced-heading= hits, all from Markdown =**bold**= in an org file, which org reads as a level-2 heading when it starts a line. 48 bold spans total, 14 of them line-initial. This half is not mechanical: converting to org =*bold*= is 48 edits, and =lint-org --fix= would rewrite the line-initial ones without knowing they are emphasis rather than headings. + +Grading: Cosmetic severity x every user every time = P3 = [#C]. It is most of the linter's noise on protocols.org, which is the real cost — noise that trains the reader to skip the report. + +Not =:solo:= — both files are synced templates. + +Source: winvm link-integrity pass, 2026-07-28. + +** DOING [#B] Finish context-engineering rightsizing :refactor: +:PROPERTIES: +:LAST_REVIEWED: 2026-07-27 +:END: +Started 2026-07-27 from three Anthropic posts Craig supplied. Always-loaded rules went from ~57,800 tokens to ~28,949, plus 13,461 path-scoped. Shipped: =paths:= frontmatter on the three file-type rules, the per-project generic-rule de-duplication, =commits.md= split into a 2,804-token invariant core plus the =publish= skill, =testing.md= split into a 347-word directive plus the =testing-standards= skill, the approval-gate signal fixed from =.ai/=-tracking to remote host, and the first-person directive. + +*What remains is Craig's decisions, not execution.* Each of these needs him: + +1. *C1 — =verification.md= (3,388 tok).* The Opus 5 guide says explicit verification instructions cause over-verification and should be removed. His standing direction is never guess, always check. My read: the honesty core (don't claim a green suite you didn't run) stays and shortens, the process injection (green baseline, suite-as-its-own-step) moves to the publish skill. His call — and it's the rule closest to a preference he's stated outright. +2. *=interaction.md= (3,828 tok, now the largest).* Carries genuinely universal output constraints (no popup menus, no reverse-video markup) plus the new peer-reasoning contract. Splitting it means deciding which parts must fire on every turn. +3. *The TDD rationalization table.* Moved to =testing-standards= rather than cut. The posts argue that kind of over-argument is counterproductive on current models. Deleting his defense against me skipping TDD is his call. +4. *D3 — the gate separation.* Which approval gates are preference (he wants to see what goes out under his name) versus guardrail (written when the worst case was worse). They read identically in the files; only he can tell them apart. Highest-leverage input remaining. + +*Do first:* the three docs in =working/context-engineering-rightsizing/= are one commit behind — they were corrected at d74d98d, before the two splits and the gate fix. Reconcile before deciding anything from them. + +Risk on the record: =testing.md='s margin is thinner than =commits.md='s. If =testing-standards= fails to trigger mid-test-writing the mocking-boundary rules are lost — a quality regression, visible in review, but a real bet where =commits.md='s moved half was purely procedural. + +** TODO [#B] Recurring-loop mechanics as a shared rule :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-07-27 +:END: +Work proposes promoting the pattern behind its 2026-07-27 auto-mode triage-intake into a standing rule covering all recurring agent tasks: fixed interval via =CronCreate= rather than dynamic self-pacing, a subagent per firing so raw scan output never reaches the orchestrator, silence with no heartbeat when subagent-backed, and accumulate-don't-mutate between closes with explicit "close the X" / "stop the X" verbs. Likely touches =triage-intake.org= auto mode, =inbox.org= monitor mode, and a new short rule in =claude-rules/= so individual workflows point at one definition of cadence, isolation, and silence. + +Points 1, 2, and 4 mostly promote existing practice. Point 3 changes documented behavior and needs a real decision. Three findings from the skeptical review, all to resolve before this ships: + +1. *Point 1 is too absolute.* Fixed interval is the right default, but not the right universal. A loop waiting on unpredictable external state (a CI run, a deploy queue) should pace to how fast that state actually changes, which is what dynamic scheduling exists for. Write it as "default to a fixed interval; use dynamic pacing only when polling external state whose timing you can't predict." +2. *Point 2 collides with a standing instruction.* Craig's harness prompt says not to spawn subagents unless he requested it. Making subagent-per-firing the standing pattern needs that reconciled explicitly — the honest reading is that asking for the loop *is* the request, and the rule should say so rather than leaving two instructions to fight. The isolation argument itself is sound and matches the Opus 5 guidance (delegate for genuinely independent, sizeable work). +3. *Point 3 has a silent-failure hole.* Removing the heartbeat means a loop that died looks exactly like a loop quietly finding nothing. "The subagent completing is proof it ran" only holds if a *failed* subagent still surfaces. Either keep a rare heartbeat (hourly, not per-fire) or specify that failure always breaks silence. Suppressing success is fine; suppressing failure is not. + +Also underspecified: what counts as "signal" for a subagent-backed loop. And the silent-until-signal spec (=docs/specs/2026-07-20-silent-until-signal-monitors-spec.org=, IMPLEMENTED) documents the per-fire heartbeat, so it needs a superseding history line rather than a silent contradiction. + +*** 2026-07-27 Mon @ 16:55 Work accepted all three findings and sharpened point 3 + +Work agreed without pushback and corrected my either/or on point 3, which was too weak. Both mechanisms are needed, not one: a failed or hung subagent breaking silence covers a *scan-level* failure, but only a periodic heartbeat catches the *scheduler* dying — because in that case nothing spawns at all and there is no failure to report. Heartbeat rare (hourly), not per-fire. + +The live consequence makes it urgent rather than theoretical: =CronCreate= auto-expires recurring jobs after seven days, so any fully-silent loop is *guaranteed* to die quietly. Work's auto-triage loop is running under exactly that contract right now. + +Work also added the reason that makes point 2's carve-out principled and should go in the rule text: the subagent exists to keep N sources' worth of raw scan output out of the orchestrator across a multi-hour loop, not to parallelize. + +Craig's call on point 3 is pending; work is surfacing it and will send the answer. + +Source: work handoff 2026-07-27 14:51, reply 16:55. + ** TODO [#B] Sentry triage split — work mail and messengers in, personal mail out :bug: :PROPERTIES: :LAST_REVIEWED: 2026-07-27 @@ -90,26 +301,13 @@ The proposed Claude-memory migration auditor is related only by runtime portabil No prepared diff: this is a shared configuration design decision, and the current local wrappers/configs remain machine-owned evidence rather than canonical source. Say "spec the MCP registry sync" to start the decisions walk. -** VERIFY [#B] Parked: telegram source treats "down" as launch, not SCAN FAILED (from .emacs.d) +** VERIFY [#B] A SCAN FAILED source must not advance its sentinel (engine, not the plugin) :PROPERTIES: :LAST_REVIEWED: 2026-07-24 :END: -What arrived: a superseding handoff (the 17:23 setq-only version is retained as context but not the one to take). Both work and home independently hit the same failure — the telegram source, finding telega down or unloaded (its *normal* entry state), reported "SCAN FAILED: telegram — not loaded" or ran a blind sweep, instead of running Step 1 to launch it. Neither hit a segfault. The recovery IS Step 1: =(telega t)= both loads the package and starts the docker server. - -Root cause is wording, not code: the Quick Reference said "never skips because the server is down" but the closing paragraph said "if any lifecycle step fails ... reports SCAN FAILED", and two agents conflated "server is down" with "a lifecycle step failed" → blind sweep without ever attempting the launch. - -The fix (33-line diff, verified present): a directive after the Quick Reference that down/not-loaded is the *trigger* to launch, never a skip; the =:ENABLED:= guard tests whether telega is *installed* (=fboundp=), not whether the server is up; SCAN FAILED reserved for a launch that was attempted and didn't reach Ready; a note that a blind sweep is worse than a clean failure because it hides real unread behind a false all-clear. Also keeps the earlier =(setq telega-use-docker t)= segfault guard in Step 1 — both projects confirmed it's a real latent guard though not the cause here. - -Recommendation: accept the superseding version. The wording defect is real and reproduced by two projects, and a triage source silently reporting all-clear on a mailbox it never scanned is exactly the false-negative class that matters. +Promoted to top-level 2026-07-28 when its parent closed — it is a separate engine question and would have been buried under a DONE parent. -Prepared: [[file:working/triage-telegram-down-launch/proposed.diff]] and the full proposed file beside it. -Say "approve the parked telegram fix" and it gets applied. - -*** VERIFY a SCAN FAILED source must not advance its sentinel (engine, not the plugin) -:PROPERTIES: -:LAST_REVIEWED: 2026-07-24 -:END: -Secondary finding from the same handoff, flagged for your judgment because it's *engine* behavior in =triage-intake.org=, not the telegram plugin. work reported that after a SCAN FAILED, "the marker still advanced" — and telegram is =:ANCHOR: none=, so something advanced a cursor it shouldn't have. The compounding harm: a source that reports SCAN FAILED but advances its window means the next sweep believes it already covered that window, so the blind-sweep hole persists across sweeps rather than self-healing. Not touched .emacs.d-side; needs a look at the engine's per-source last-run/anchor advance. +Secondary finding from the 2026-07-24 handoff, flagged for your judgment because it's *engine* behavior in =triage-intake.org=, not the telegram plugin. work reported that after a SCAN FAILED, "the marker still advanced" — and telegram is =:ANCHOR: none=, so something advanced a cursor it shouldn't have. The compounding harm: a source that reports SCAN FAILED but advances its window means the next sweep believes it already covered that window, so the blind-sweep hole persists across sweeps rather than self-healing. Not touched .emacs.d-side; needs a look at the engine's per-source last-run/anchor advance. ** TODO [#B] cj-remove-block still can delete the WRONG cj block :bug: :PROPERTIES: @@ -2121,3 +2319,72 @@ Fix direction (per home): while inside a =begin_example= / =begin_src= block, sk Home answered it and I re-verified both halves here: =grep invalid-block= over =lint-org.el= returns nothing, and =org-lint--checkers= enumerates =invalid-block= in batch Emacs alongside =link-to-local-file=, =invalid-babel-call-block=, and =missing-language-in-src-block=. So this is the same shape as the =link-to-local-file= episode: suppress an =invalid-block= finding whose line falls inside a verbatim block, on our side of org-lint's output. No local checker to edit. Regression fixture, ready to use: home's own =.ai/notes.org= PENDING DECISIONS example block (lines 386-398) holds an unescaped =** Feature Name or Topic= and trips both delimiters — findings at lines 386 and 398. Home is deliberately leaving its copy unescaped so it stays a fixture, and asked to be pinged when the filter lands so it can re-run. The filter should take those two findings to zero without touching the file. +** DONE [#C] sentry.org calls one loop cycle a "fire" :chore:solo: +CLOSED: [2026-07-28 Tue] +:PROPERTIES: +:LAST_REVIEWED: 2026-07-28 +:END: +Done 2026-07-28. 72 noun-sense instances in =sentry.org= became "cycle"; the four verb-sense uses stayed. Three more lived outside the file — =wrap-it-up.org= ("a crashed fire"), =todo-cleanup.el= and its test ("every sentry fire") — all naming a sentry cycle, so they moved too. home's proposal was scoped to =sentry.org= alone, so the leak would have split the vocabulary across files. + +Craig read home's "nine fires" as nine emergencies and went looking for what was burning (2026-07-28): "I assume you mean nine crises, not nine loop cycles and I begin to get scared." The term reaches him directly — digest headings render as =** Fire 11 — 08:32 CDT= in the anchor he reads every morning. 35 instances in =sentry.org=. + +Grading: Minor severity (a user-facing artifact that miscommunicates, no data loss) x most users frequently (every digest, on every project running sentry) = P3 = [#C]. + +*Take the problem, not home's proposed term.* home proposed "pass", reasoning that it already lives in the file's vocabulary. That is exactly what disqualifies it. =sentry.org= already uses "pass" as a precise numbered noun: "the pass list", "the Pass Runner", "eleven finding/hygiene passes", "pass 12" for the implementation pass. There are exactly eleven hygiene passes, so home's proposed digest heading =** Pass 11= collides with an existing real referent. Renaming would trade a term Craig misreads as urgent for one that is genuinely ambiguous. + +Counter-proposal: *cycle*. It appears zero times in =sentry.org=, so there is nothing to collide with. It is also Craig's own word from the very quote that surfaced this ("not nine loop cycles"). =** Cycle 11 — 08:32 CDT= reads cleanly. Checked and rejected: "sweep" (already used for hygiene and property sweeps) and "run" (already used as a noun, "first live run"). + +Keep the verb sense of fire throughout ("the notify fires", "the path never fires") — only the noun meaning one loop cycle changes. Past session anchors are historical records and stay as written. + +Craig approved "cycle" on 2026-07-28. That settles the only judgment the task carried, so it is =:solo:= now: the surface is the 35 noun-sense instances in =sentry.org=, and the completion check is objective — zero noun-sense "fire" left, verb sense untouched, lint clean, suite green, canonical and mirror in sync. + +Source: home handoff, 2026-07-28. +** DONE [#B] references/ is linked from protocols.org but never synced :bug: +CLOSED: [2026-07-28 Tue] +:PROPERTIES: +:LAST_REVIEWED: 2026-07-28 +:END: +Craig picked option 1 on 2026-07-28: drop the link, point at the calendar workflows instead. The four of them sync already and carry the MCP tool names, both account ids, the gcalcli fallback, and the conflict-check discipline — everything the reference was cited for. + +The adversarial review then returned =Needs Discussion= and widened the fix twice, both correctly: + +- My first replacement said credentials "live in the rulesets repo" without naming a file. The only calendar-named document there was =calendar-reference.org=, whose three credential paths have all been dead since the OAuth keys moved into the encrypted MCP bundle in May. So the prose sent a reader to a stale file, which fails more quietly than the dead link it replaced. Now names =mcp/README.org=, the real authority, verified to document =gcp-oauth.keys.json= as gitignored and regenerated at install. +- =calendar-reference.org= was left orphaned by the link removal: zero live inbound references, two copies, and =references/= is not in =sync-check.sh='s gate (=paths=(protocols.org workflows scripts)=), so the copies could drift silently. Deleted both, and the empty =references/= directories with them. Its operational content is fully covered by the four workflows and its credential paths were all stale, so nothing live was lost. + +The review also found the same defect class at seven other sites, filed separately. + +One fact died with the file, dropped deliberately rather than by accident: that the Google Cloud app runs in production mode, so tokens don't expire after seven days. It's checkable in the console, and it was the last live line in a document whose other credential facts had all gone stale. + +=protocols.org:273= links to =references/calendar-reference.org=, but startup.org's rsync copies only =protocols.org=, =workflows/=, and =scripts/=. So the link is dead in every consuming project. Confirmed: the file exists at =claude-templates/.ai/references/=, and neither home nor =.emacs.d= has a =.ai/references/= at all. + +Grading: Minor severity (a documented reference an agent can't follow, workaround is to search or ask) x every user every time (every consuming project, every sync) = P2 = [#B]. + +Pinned 2026-07-28 for Craig's decision. Analysis below is complete; only the choice is open. + +*Revised recommendation: drop the link, don't add the sync.* My first read was add =references/= to the rsync. Looking at what the directory actually holds reversed it: + +- =references/= holds exactly one file, and =protocols.org:273= is its only citation anywhere in the tree. +- The four calendar workflows (=add-=, =edit-=, =delete-=, =read-calendar-event(s).org=) already sync to every project, and already carry the operational detail: the MCP server name, both account IDs, the gcalcli fallback, conflict-checking. None of them cites =calendar-reference.org=; they are self-sufficient. +- What the reference uniquely adds is credential *file locations* (an OAuth keys path, a GPG-encrypted gcalcli secret) — no secret values. Re-auth is a rare operation Craig performs himself, not something an agent in another project needs a pointer to. + +So adding a synced directory carrying =--delete= semantics, to deliver one mostly-redundant file, is a poor trade. It also cuts against the rightsizing work: =protocols.org= is read into context every session, and a dead link is noise in a file being slimmed. + +Preferred fix: replace the link with a one-line pointer to the calendar workflows, which travel and are current. The reference file stays rulesets-only for the credential locations. + +Alternatives if Craig prefers: add =references/= to the rsync (the =--delete= hazard is not present today — work is the only project with a =.ai/references/= and its copy is byte-identical), or fold the credential locations into the calendar workflows and then drop the link (most complete, but spreads local absolute paths across four more synced files). + +Not =:solo:= — it changes a synced template, which needs Craig's approval by the inbox rule, and the sync-vs-drop choice is his. + +Source: winvm link-integrity pass, 2026-07-28. +** DONE [#B] Parked: telegram source treats "down" as launch, not SCAN FAILED (from .emacs.d) +CLOSED: [2026-07-28 Tue] +:PROPERTIES: +:LAST_REVIEWED: 2026-07-24 +:END: +Applied 2026-07-28, merged with the segfault root-cause fix that arrived the same morning rather than applied alone. + +Merging was necessary, not tidiness. The parked proposed file still carried the bad =(telega--loadChats 'main)= call at its own lines 52 and 122, so applying it as-is would have shipped a file that fixed the wording defect while preserving the call that kills the server. Its third hunk also added prose citing "tdlib segfaults in native mode (SEGFAULT gotcha below)" — pointing at the section the new handoff rewrites to say those deaths were our own bad argument, not tdlib memory corruption. + +What landed: all three parked hunks (the down-is-launch directive, the SCAN-FAILED-only-after-launch-attempted rewording, the =(setq telega-use-docker t)= restored to the Step 1 code block), plus both corrected =loadChats= call sites and the rewritten gotcha. The native-mode prose was reconciled in two places so it no longer leans on the refuted story: the Step 1 comment now states plainly that docker mode and the loadChats bug are separate concerns (the deaths happened *in* docker mode, so docker mode is neither a defense against it nor evidence for it), and the Quick Reference line says "crashed in native mode (2026-06-09)" instead of "segfaults", with the same disambiguation. + +Verified: both live call sites use the TL object; the two remaining ='main= occurrences are inside the gotcha prose describing the bug. lint-org clean, mirror synced, suite green. diff --git a/voice/SKILL.md b/voice/SKILL.md index cb378a2..cdf7874 100644 --- a/voice/SKILL.md +++ b/voice/SKILL.md @@ -300,7 +300,7 @@ These patterns carry Craig's writing voice. Most apply in **both** prose mode (e ### 32. First-Person Voice Rewrite [personal] -**Rule.** Rewrite impersonal third-person publish-artifact bodies into first person ("I added X", "I kept Y because..."). The commit subject line stays imperative per Conventional Commits. Skip for mechanical changes where the subject alone carries the message. +**Rule.** Rewrite impersonal third-person publish-artifact bodies into first person ("I added X", "I kept Y because..."). **The "I" is Craig**, who is the author of record and whose name the artifact goes out under — not an agent narrating work done on his behalf. Cut any construction that writes an agent in as a separate party ("Craig asked me to", "I filed this for Craig", "needs Craig's decision"); an open decision is his own, written as "I haven't decided whether…". The commit subject line stays imperative per Conventional Commits. Skip for mechanical changes where the subject alone carries the message. See `voice/references/voice-profile.org` §32 for problem, basis, examples, and history. diff --git a/working/nag-event-vocabulary/2026-07-30-1646-from-home-vocabulary-to-spread-craig-named-a.org b/working/nag-event-vocabulary/2026-07-30-1646-from-home-vocabulary-to-spread-craig-named-a.org new file mode 100644 index 0000000..cd1d190 --- /dev/null +++ b/working/nag-event-vocabulary/2026-07-30-1646-from-home-vocabulary-to-spread-craig-named-a.org @@ -0,0 +1,15 @@ +#+TITLE: Vocabulary to spread: Craig named a pattern today and asked +#+SOURCE: from home +#+DATE: 2026-07-30 16:46:50 -0500 + +Vocabulary to spread: Craig named a pattern today and asked that it reach every project rather than living only in home. + +The words are 'nag event', 'nag deadline', and 'nag me about this'. Any of them means build this exact construction without asking for the shape again. + +The calendar event: an all-day event on the deadline date, in his primary personal calendar (Google Calendar today, but follow whatever the primary personal calendar is in future). Notifications on each of the three preceding days and again on the deadline itself, so four in total. The subject is the action phrased as the thing to do, so 'Return shoes' rather than 'Shoe deadline'. The description carries a link to a Google Keep note of the same title. + +The Keep note: a text note, explicitly not a checklist. Same title as the event so the pair reads as one thing. The goal goes first, before anything else, so opening it cold tells him what he is trying to achieve. Every step on its own line. Detailed enough to finish the task without looking anything else up, which means order numbers, measurements, decision rules, links and dates all live in the note. Where no steps are planned yet, write the recommendation in the same shape instead. + +The reason it is built this way is worth carrying with the rule. His failure mode on deadlines is not forgetting they exist, it is deferring the decision until the window closes and then owning the outcome by default. Four notifications across four days beat one ping, and the linked note removes the 'I would have to work out what this involves' friction that causes the deferral. + +Origin was a shoe return window on 2026-07-30. I have it in home's memory; sending it here so it is available wherever he says the word. diff --git a/working/nag-event-vocabulary/2026-07-30-1653-from-home-amendment-to-the-nag-event-vocabulary-i.org b/working/nag-event-vocabulary/2026-07-30-1653-from-home-amendment-to-the-nag-event-vocabulary-i.org new file mode 100644 index 0000000..3b5162b --- /dev/null +++ b/working/nag-event-vocabulary/2026-07-30-1653-from-home-amendment-to-the-nag-event-vocabulary-i.org @@ -0,0 +1,11 @@ +#+TITLE: Amendment to the nag-event vocabulary I sent earlier today. +#+SOURCE: from home +#+DATE: 2026-07-30 16:53:42 -0500 + +Amendment to the nag-event vocabulary I sent earlier today. Craig added two elements to the Keep-note half of the pattern. + +The note is coloured burnt orange, and the note is pinned. Both are part of the spec rather than decoration. The colour makes nag notes identifiable at a glance among his other Keep notes, and pinning keeps a live deadline at the top where it belongs rather than sinking down the list. + +So the full Keep-note spec is now: text note not checklist, same title as the calendar event, goal stated first, every step on its own line, detailed enough to finish without looking anything else up, burnt orange, pinned. + +One practical note for whoever implements this. The google-keep MCP currently shows as a connected server but exposes no tools, so a note cannot be created, coloured or pinned programmatically. The workaround today was to write the note text, put it on the clipboard with wl-copy, and hand the colour and pin steps to Craig, then ask him for the note URL because the calendar event description needs it. Worth flagging in the rule so nobody assumes the automation exists. diff --git a/working/sentry-arming-correction/2026-07-30-0736-from-work-sentry-org-the-arming-mechanism-was.org b/working/sentry-arming-correction/2026-07-30-0736-from-work-sentry-org-the-arming-mechanism-was.org new file mode 100644 index 0000000..d73a237 --- /dev/null +++ b/working/sentry-arming-correction/2026-07-30-0736-from-work-sentry-org-the-arming-mechanism-was.org @@ -0,0 +1,22 @@ +#+TITLE: sentry.org: the arming mechanism was wrong, and it made sent +#+SOURCE: from work +#+DATE: 2026-07-30 07:36:49 -0500 + +sentry.org: the arming mechanism was wrong, and it made sentry unusable as documented. + +Sending the edited .ai/workflows/sentry.org from the work project. The canonical needs the same change so every sentry-capable project gets it. + +What was wrong. Entry step 7 said to arm with /loop, and justified it by saying a detached schedule hits a headless-auth wall for MCP. That reasoning is sound for a system cron or at job spawning a fresh headless agent, but it is not what we actually use. CronCreate schedules a prompt inside the arming session, so MCP auth is inherited. The work project proved this overnight on 2026-07-28/29: cron-driven triage sweeps read Gmail, Slack, Linear and both calendars for hours. + +The practical cost of the error: I told Craig this morning that I could not arm sentry because /loop had to come from him. That was wrong, and it is the second time the doc's stated mechanism diverged from his actual practice, which has been at or cron with each round scheduling the next. + +What changed: + +1. Step 7 rewritten for CronCreate, documenting both shapes. Recurring, where the single-runner lock covers overlap. And self-rescheduling one-shots, which is Craig's established practice and makes serialization structural rather than lock-dependent, with the interval measured from end-of-fire rather than wall clock. +2. Three constraints added that the file did not carry and that decide how sentry can be used at all. CronCreate jobs are session-only and in-memory, so sentry survives exactly as long as the session that armed it and closing the terminal ends it. Fires run inside that session, hence the inherited auth. Recurring jobs auto-expire after seven days. +3. Stop Sentry now says CronList then CronDelete, with a check that no sentry job survives, rather than 'stop the /loop (ScheduleWakeup stop)'. +4. The overview and the interval trigger reworded off loop language. + +One thing I deliberately did not change, and it is worth a second opinion. Pass 3 excludes mail and messenger sources on Craig's 2026-07-21 ruling. My first draft of the new section asserted that inherited auth means the pass is no longer restricted, which silently overturned that ruling by inferring a technical cause for a policy decision. I caught it and replaced it with a note saying the exclusion is a choice rather than a wall, so nobody reasons from 'sentry cannot reach Gmail'. If the canonical wants the exclusion revisited now that the auth story is clear, that is Craig's call rather than a doc edit. + +Companion file to reconcile: nothing in the same directory references the arming mechanism, but a grep for '/loop' across the templates would be worth running, since triage-intake.org's auto mode carries the same headless-auth claim in its 'Trigger and delivery' section and is likely wrong for the same reason. diff --git a/working/sentry-arming-correction/2026-07-30-0736-from-work-sentry.org b/working/sentry-arming-correction/2026-07-30-0736-from-work-sentry.org new file mode 100644 index 0000000..2a57d17 --- /dev/null +++ b/working/sentry-arming-correction/2026-07-30-0736-from-work-sentry.org @@ -0,0 +1,244 @@ +#+TITLE: Sentry — Overnight Hygiene Supervisor +#+AUTHOR: Craig Jennings +#+DATE: 2026-07-19 + +* Overview + +Sentry is a scheduled interval sweep (=CronCreate=, armed in and bound to the arming session) that keeps a project's hygiene current while Craig is away. Each fire walks a fixed list of passes — roam pull, inbox zero, triage (no mail or messengers), todo cleanup, task audit, working-files hygiene, spec board, link integrity, git health, prep freshness, bug and refactor finding, and (opt-in) solo-task implementation — and commits each pass's writing to a throwaway daily branch. Nothing pushes. In the morning Craig reviews the branch, squash-merges what he wants, and deletes it. + +The design goal is a project that greets the morning already tidy, with every judgment call and every destructive action parked in an approval queue rather than executed unattended. Sentry does the mechanical sweeping; Craig does the deciding. + +This file is the engine. It owns the entry gates, the branch mechanics, the lock model, the per-fire pass runner, the digest and approval queue, the skip semantics, and the stop-sentry shutdown. The =agent-lock= helper (=.ai/scripts/agent-lock=) provides the locks. The passes reuse existing workflows (=inbox.org=, =triage-intake.org=, =clean-todo.org=, =task-audit.org=) under sentry's unattended contract. + +* When to Use This Workflow + +Craig arms sentry at the end of a session, with the machine left running, to have overnight hygiene done by morning. + +Triggers: + +- "start sentry", "run sentry", "arm sentry", "sentry mode" +- "let sentry watch this overnight", "keep this tidy overnight" +- "start sentry hourly", "start sentry every <interval>" (sets the fire interval) + +Stop trigger (see Stop Sentry below): + +- "stop sentry", "stand down sentry", "sentry off" + +Sentry is deliberately *not* auto-armed. Running it in a project is a per-project grant (the =:COMMIT_AUTONOMY:= marker) plus a deliberate launch with Craig at the terminal for the entry gates. + +* Prerequisite — the autonomy ticket + +Sentry commits unattended. =commits.md= gates commits on Craig's approval, so sentry needs standing, per-project authorization to run at all. Before anything else, read the project's =.ai/notes.org= Workflow State block for: + +: :COMMIT_AUTONOMY: yes + +If the marker is absent or not =yes=, decline to start and name the marker: + +: Sentry needs ":COMMIT_AUTONOMY: yes" in .ai/notes.org Workflow State to run — it commits unattended. Add it to grant, or run the hygiene passes by hand. + +No half-running mode: a project without the grant doesn't run sentry's read-only passes either. The grant is one line away, so this is a deliberate opt-in, not a barrier. + +A second, *independent* marker gates the solo-task implementation pass (pass 12): + +: :SENTRY_MAY_IMPLEMENT: yes + +=:COMMIT_AUTONOMY:= lets sentry commit its hygiene sweeps to the branch; =:SENTRY_MAY_IMPLEMENT:= additionally lets it implement solo, decision-free backlog tasks on the branch. The split exists because the two carry different morning costs: hygiene is a two-minute merge, implemented code is a review session. A project can run hygiene-only sentry without the implement pass, and most should until sentry has quiet weeks behind it. Absent =:SENTRY_MAY_IMPLEMENT:=, pass 12 skips; sentry still runs every other pass. Requires =:COMMIT_AUTONOMY:= alongside it — implementing implies committing. + +* Entry — interactive, with Craig present + +Craig types the sentry trigger, so the first moves run with him at the terminal. Do them in order; each gate that fails stops entry until Craig answers. + +1. *Autonomy ticket* — the prerequisite above. Absent → decline and stop. + +2. *Dirty-tree gate.* =git diff --quiet HEAD= (tracked modifications only; untracked and gitignored files never block — an inbox drop or scratch file is not in-progress work). If the tracked tree is dirty, describe what's dirty and offer, inline-numbered per =interaction.md=: + + 1. Finish the job — commit the in-progress work first (recommended if it's a coherent unit) + 2. Stash it — =git stash= and start sentry on a clean tree + 3. Roll back named changes — discard specific files (names them) + + Wait for an answer. Sentry can't start unattended from a dirty state; that's the point. + +3. *Green-suite gate.* Run the project's full suite (=make test=, or the project's equivalent — detect it). Read the output. If anything is red, describe the failures and offer to investigate before arming. The loop starts only on a green baseline, because every unattended fire measures itself against "did I break this?" and a pre-existing red poisons that check. + +4. *Prior sentry branch.* =git branch --list 'sentry/*'=. An unmerged =sentry/*= branch from a previous night means the morning review didn't happen. Surface it and offer to squash-merge or delete it now (Craig is present); don't stack a second sentry branch on the first. + +5. *Reconcile the project branch.* Fetch and fast-forward-only against upstream — the same reconcile =startup= runs: + + : git fetch --all --prune + : git rev-list --left-right --count @{u}...HEAD + + Zero-behind → continue. Behind-only and clean → =git merge --ff-only @{u}=. Diverged → surface to Craig (he's present); don't auto-resolve. + +6. *Create the daily branch.* From HEAD: + + : git switch -c "sentry/$(date +%F)-$(uname -n)" + + The host suffix (=uname -n=) stops a same-date collision between the two daily drivers. The working tree now sits on this branch overnight — the launch hands the repo to sentry until the morning merge. Reclaiming it mid-night means stopping sentry first (see Stop Sentry). Note the Emacs buffer-revert caveat to Craig if he has the repo open: files change on disk under him overnight, so buffers want reverting after the morning merge (see =emacs.md=). + +7. *Arm the schedule.* Use *=CronCreate=*, not =/loop=. Default hourly; Craig's "every <interval>" phrase overrides. The fire prompt is one sentry fire (the Pass Runner below), written so a fresh context can execute it — it names this file, so the fire re-reads the workflow rather than relying on a conversation it cannot see. + + Two shapes, both valid: + + - *Recurring* (simplest): one =CronCreate= with =recurring: true= and a cron expression at the interval. The single-runner lock below handles the overlap case, so a long fire never gets a second fire on top of it. Stop by deleting the job. + - *Self-rescheduling* (Craig's established practice): =recurring: false=, and the last step of each fire creates the next one-shot job. Serialization is then structural rather than lock-dependent, and the interval measures from end-of-fire instead of wall clock, so a slow fire doesn't compress the next gap. Stopping is simply not rescheduling. + + Pick an off-minute rather than =0= or =30= (=7 * * * *=, not =0 * * * *=). + + Confirm the arming in one line: mechanism, interval, branch name, project. + + *Three constraints that decide how sentry can be used, and they were wrong in this file until 2026-07-30:* + + - *=CronCreate= jobs are session-only and in-memory.* They are not written to disk and they vanish when the Claude session exits. Sentry therefore survives exactly as long as the session that armed it. Tell Craig this at arming time: closing the terminal ends sentry, and the branch is left wherever the last fire got to. + - *Fires run inside the arming session, so MCP auth is inherited.* This is why sentry's triage pass can reach Gmail, Slack, Linear and the calendars at all. An earlier version of this file claimed a detached schedule hits a headless-auth wall and prescribed =/loop= to avoid it; that reasoning applied to a *system* =cron= or =at= job spawning a fresh headless agent, and it does not apply to =CronCreate=. Proven in the work project overnight on 2026-07-28/29, where cron-driven triage sweeps ran mail, Slack, Linear and calendar reads for hours. + - *Recurring jobs auto-expire after seven days*, firing one last time before deletion. Irrelevant for an overnight run; it bounds anything longer. + + Note what this does *not* change. Pass 3 still excludes mail and messenger sources, because that is Craig's ruling of 2026-07-21 and not a capability limit. Inherited auth means the exclusion is a *choice* rather than a wall, so don't reason from "sentry can't reach Gmail" — it can, and it is told not to. Overturning that needs Craig saying so for a given run, not an inference from this section. + +* The lock model + +Two locks, both served by =.ai/scripts/agent-lock= (names only; the helper owns the paths, which live on tmpfs under =$XDG_RUNTIME_DIR/agent-locks/=, host-local and cleared on reboot). + +*Single-runner lock* (=sentry-<project>=, where =<project>= is the repo-root basename: =basename "$(git rev-parse --show-toplevel)"= — the same derivation =wrap-it-up.org='s guard uses, so the two agree on the lock name). Each fire acquires it at fire start and releases it at fire end, and refreshes it between passes (the heartbeat, so a live fire's lock never ages past one pass). If the schedule fires again while a previous fire still holds it, the new fire's acquire fails and the fire skips with one digest line — no two fires run at once. (Under the self-rescheduling shape this cannot arise, since the next job is only created once the current fire ends; the lock is the belt-and-braces for the recurring shape.) The bounded wait is short (a few seconds); a live fire means defer, not queue. + +*Roam-write lock* (=roam-write=). A pass that edits a file under =~/org/roam= acquires it, runs =capture-guard --wait= (the human-capture layer stays underneath), edits the working tree, triggers =systemctl --user start roam-sync.service=, and releases. The lock spans only edit-plus-trigger. Sentry never runs =git= against =~/org/roam= — roam-sync stays the repo's only committer (the 2026-06-24 one-git-owner rule). Pass 1's =pull --ff-only= is the sole, read-only exception. + +Every reclaim of a stale lock surfaces in the digest — the helper prints the reclaim note, and the fire records it. A reclaim during a genuinely slow pass is possible, so it's never silent. + +* The Pass Runner — one contract per pass + +Each fire, after acquiring the single-runner lock and verifying branch state (below), walks the pass list in order. Every pass follows the same four-step contract: + +1. *Probe* — a cheap existence check for the pass's target (named per pass below). Absent → the pass is one skip line in the digest and nothing more. This is what makes the pass list portable: passes self-activate where their target exists and stay silent elsewhere, with zero per-project configuration. + +2. *Work* — run the pass under the unattended contract. Quick, solo, already-agreed mechanical actions execute. Anything destructive or requiring judgment does *not* execute — it appends to the morning-approval queue (what, why, the exact command or edit that fires on approval). A pass runs fully or not at all; there is no reduced-form pass. + +3. *Session-context entry* — a pass that does or queues work appends its digest line to the =session-context.org= Session Log (path resolved via =.ai/scripts/session-context-path=) before its commit, so a crash between them still leaves the trail. Per-pass lines for an all-quiet fire (every pass probe-skipped or no-op) are not written one by one — the fire collapses to a single heartbeat at fire-end (below), so an idle fire doesn't spray one skip line per pass. + +4. *Commit* — if the pass wrote to disk, commit it: =chore(sentry): <pass> — <what changed>=. One commit per writing pass. A probe-skip or a no-op pass writes nothing and commits nothing. + +Between passes, refresh the single-runner lock (=agent-lock refresh sentry-<project>=) — the heartbeat. + +** Branch-state verification (fire start, before the passes) + +After acquiring the lock, confirm the fire is safe to run: + +- *On the right branch* — HEAD is =sentry/<today>-<host>=. If the schedule was armed on a prior day and crossed midnight, the branch keeps the arming date; that's fine, morning teardown handles it. If HEAD is somehow *not* a sentry branch (an interrupted stop, a manual checkout), skip the whole fire with a digest line rather than committing onto main. +- *Clean of foreign changes* — =git diff --quiet HEAD= excluding the spine set (=session-context.org= / =session-context.d/=, resolved via =session-context-path=). Sentry's own spine writes must not trip this; a genuinely unexpected dirty tree (something outside the spine changed and wasn't committed by a prior pass) poisons the fire — skip it with a digest line, the next fire retries. + +* Unattended safety — skip, never degrade + +With no one at the terminal, any unsafe state makes the affected scope skip with one digest line, and the next fire retries. Unsafe states and their scope: + +- *Unexpected dirty tree* (non-spine) → skip the whole fire. +- *Lost or un-acquirable single-runner lock* → skip the fire (another fire holds it, or the helper is missing). +- *A pass's own precondition unmet* (its probe fails, or a dependency is dirty) → skip that pass only. +- *Red suite at fire-end* (see below) → the commits stay on the branch, flagged in the digest for morning review; the fire doesn't roll back. + +Skips are never silent and never partial. Inside a *working* fire, a pass line means the pass fully ran and a skip line names why it didn't. An *all-quiet* fire is not a silent skip either: its single =sentry at HH:MM: nothing= heartbeat is the explicit record that every pass found nothing, standing in for a wall of identical skip lines. The anti-silence rule targets a pass that hides work it should have surfaced; a quiet fire has surfaced that there was none. + +** Multi-day stall notification + +An unmerged prior =sentry/*= branch at fire start (the morning review never happened) skips the fire. After the *second consecutive* fire skipped for this reason, send one persistent desktop notification naming the project and branch: + +: sentry stalled: <branch> unmerged — merge or delete to resume + +Then repeat at most daily. Persistent notify matches the paging convention — it stays on screen until dismissed. A multi-day stall never stays silent. + +* The pass list (v1) + +In order. Each names its detection probe. A pass whose probe fails is one skip line. + +1. *Roam pull* — =git -C ~/org/roam pull --ff-only=. Probe: =~/org/roam= is a git clone. Skipped when the roam tree is dirty (roam-sync owns that case) or the clone is absent. Read-only and ff-only — the one narrow exception to "don't touch roam git," so later passes read a fresh tree. + +2. *Inbox zero* — run =inbox.org= roam mode under the no-approvals contract: quick+solo+agreed items execute, shared-asset and convention proposals park (prepared diff, =VERIFY= task, sender reply) in the approval queue. Edits to =~/org/roam/inbox.org= take the roam-write lock + =capture-guard=. Probe: the roam clone or a project =inbox/= exists. Tidying the shared roam inbox is allowed from *any* project session, work included — it's housekeeping on a shared resource, not a durable KB-node write, so the work-denylist doesn't gate it (=knowledge-base.md=). Never park it as a cross-project boundary crossing. + +3. *Triage intake — mail and messenger sources excluded.* Run =triage-intake.org=, loading only its non-mail, non-messenger source plugins (calendar, PR/ticketing). The mail and messenger plugins — cmail, any Gmail variant, Telegram, Signal, chat DMs — are never loaded by a sentry fire: Craig ruled 2026-07-21 that sentry doesn't check email or messengers. A manual "triage intake" still scans everything. Probe: the project has at least one *active* triage source that survives that exclusion — a project-specific plugin (=.ai/project-workflows/triage-intake.*.org=), or a non-empty =:TRIAGE_SOURCES:= declaration naming general plugins that exist. Mere presence of the template-synced general plugins does *not* activate the pass; a project that declares no sources, or whose only declared sources are mail or messengers, probe-skips (see =docs/specs/2026-07-20-triage-source-activation-spec.org=). Destructive actions (deleting, archiving, sending) queue; they never fire unattended. + +4. *Todo cleanup* — the =clean-todo.org= mechanics (hygiene pass + =--archive-done= + =--convert-subtasks=). Probe: a root =todo.org=. Note that =--archive-done= is not purely an org-file pass on its first run in a project: it creates =archive/task-archive.org= and appends a =.gitignore= entry, so it produces a real tracked-file commit and correctly trips the fire-end conditional suite. (archangel, first live run 2026-07-21.) + +5. *Task audit* — the *mechanical subset* of =task-audit.org= hourly (staleness counts, structural checks, cookie recomputation); the judgment half (priority regrades, consolidations, merge candidates) runs *once per night* and queues its findings rather than repeating them every fire. Probe: a root =todo.org=. A full audit every hour is too heavy and re-surfaces the same judgment calls all night. (takuzu, first live run 2026-07-21.) Factual staleness fixes that are unambiguous still execute. + +6. *Working-files hygiene* — flag =working/<slug>/= directories whose backing task is closed (a filing candidate per =working-files.md=). Probe: a =working/= directory exists. The filing itself queues (it's a judgment move). + +7. *Spec status board* — the =docs-lifecycle= grep for spec keywords, surfacing any =DOING= spec whose bound build parent is closed. Probe: =docs/specs/= exists. + +8. *Link integrity* — broken =file:= links in the project's org files, via =lint-org.el=. Probe: =lint-org.el= present. Report-only into the digest; no unattended rewrites. + +9. *Git health* — uncommitted drift, unpushed commits on other branches, stale branches, main-behind-origin. Probe: =.git=. Report into the digest. + +10. *Prep + symlink freshness* — stale daily-prep docs, broken symlinks. Probe: the prep dir / symlinks exist (work and home only, in practice). + +11. *Bug and refactor finding* — hunt for real bugs and worthwhile refactoring opportunities in the project's codebase: static analysis (=shellcheck= for shell, the project's own linters for its languages), config sanity checks, plus one targeted code-reading area per fire. Rotate the area across fires and name it in the digest, so coverage accumulates over a night instead of re-reading the same corner. Randomized property sweeps (generate-and-verify against an engine's own invariants) are good quiet-fire work here, reaching past a frozen test corpus. Expect the pass to go honestly quiet after the first few fires find the standing defects; a quiet hunt is a result, not a failure. (takuzu, first live run 2026-07-21: three real fixes in the first four fires, then quiet.) This pass does *not* run the test suite — the entry baseline already ran it, and re-running it hourly is anti-pattern 5; read the entry result instead. Probe: the project carries a codebase — source under version control beyond its org and tooling files. File each verified bug as a graded task in =todo.org= per the severity × frequency matrix (=todo-format.md=), and each refactoring opportunity as a =:refactor:= task, deduped against existing tasks; an unverifiable suspicion is a digest line, not a task. *Find, never fix in this pass* — the finding files a task and stops. A fix happens only in the opt-in implementation pass below, and only after the finding is a filed task that pass then re-verifies from scratch (see the premise rule there). A freshly-found "bug" can be a misread — one was filed and retracted two fires apart on 2026-07-23 — so the file-then-verify-then-fix pipeline is deliberate: the task is the checkpoint, not a same-breath fix. (Added at Craig's order 2026-07-21, first dogfooded in dotfiles; refactor-finding added 2026-07-24.) + +12. *Solo-task implementation (opt-in — =:SENTRY_MAY_IMPLEMENT:=)* — work the backlog's solo, decision-free tasks on the branch. Probe: =.ai/notes.org= Workflow State carries =:SENTRY_MAY_IMPLEMENT: yes= *and* the project holds =:COMMIT_AUTONOMY:= (the implement pass commits). Absent the marker, skip — this pass is off by default, because it turns the morning from a two-minute merge into a code review, and that's the project owner's call. When on: invoke =work-the-backlog.org= under its unattended-loop contract (no pre-flight Q&A — there's no Craig overnight), eligibility =TODO= + =:solo:=, with the defer checklist deciding act-vs-file. The overnight-only tightening: only the *ready* bucket implements (clears every checklist item with zero open decisions); a task needing even one quick decision defers to a =VERIFY= rather than guessing, exactly as the loop caller already does. Commit each logical change to the sentry branch; *never push* — the morning review and merge is the gate, same as every other pass. The full quality bar holds (TDD, suite green before each commit, =/review-code=, =/voice=), and =/review-code= here runs the *premise check first*: reproduce the bug or confirm the problem is real before judging the diff. The review is the fact-checker that a filed claim never got, and it is what makes fixing-on-a-branch safe (Craig, 2026-07-24). A task that fails its premise check is not implemented — the finding was wrong, and that outcome is a digest line, not a commit. (Added at Craig's direction 2026-07-24: overnight implement-on-branch, gated and never-pushed.) + +(KB lesson promotion — the pass the original proposal listed eleventh — is deferred to vNext. An unattended judgment pass writing to the shared knowledge base waits until sentry has quiet weeks behind it and a designed detection heuristic. See the filed lesson-detection-heuristic task.) + +* Fire-end — conditional suite, then the digest commit + +After the passes: + +1. *Conditional suite run.* If any pass this fire modified files *outside* the org/spine set (a code-touching pass, rare but possible via fixtures), run the full suite once. A green run confirms the fire's commits are safe; a red run flags the digest for morning review — the commits stay on the branch (nothing is pushed, so the morning gate catches it). No per-pass suite runs: the entry run is the green baseline, and hourly per-commit runs would turn a seconds-long fire into minutes all night. Fires that only touched org/spine files skip this. + +2. *Heartbeat or digest, then commit.* Decide quiet vs working. A *quiet* fire — every pass probe-skipped or no-op, nothing added to the approval queue — writes a single heartbeat line to the Session Log, =sentry at HH:MM: nothing= (HH:MM local, from =date=), and no per-pass digest block. A *working* fire — any pass ran, wrote, or queued — writes its full per-pass digest block. Then commit any accumulated spine writes in one sweep: =chore(sentry): digest — <date> <time> fire= for a working fire, =chore(sentry): heartbeat — <date> <time>= for a quiet one, so even a quiet fire leaves a clean tree for the next branch-state check (where the spine is untracked, the mirror-only case, there is nothing to commit and the heartbeat line stays in the working-tree anchor). This is the silent-until-signal policy (see =docs/specs/2026-07-20-silent-until-signal-monitors-spec.org=): an all-quiet night collapses from a wall of no-op digests to a list of one-line heartbeats, while a fire that actually did or queued something still writes the full record. + +3. *Release the single-runner lock.* + +* The digest and the approval queue + +*Digest.* A *working* fire appends its block to the =session-context.org= Session Log (the spine the fire already writes), so it survives a crash, rides the session archive, and is on screen in the running session. One block per working fire: the timestamp, then one line per pass (ran + what, or skipped + why), plus any lock reclaim notes. A *quiet* fire (nothing done or queued) writes no block — just the one heartbeat line =sentry at HH:MM: nothing= (the silent-until-signal policy). The per-pass block is a working-fire artifact; it still carries one line per pass so a real skip inside a working fire is never hidden. + +*Approval queue.* Destructive and judgment actions accumulate under one heading in the same file — =* Sentry approval queue (<date>)= — newest last. Each item carries three things: *what* (the action), *why* (what triggered it), and the *exact command or edit* that fires on approval. The morning review is Craig reading this heading top to bottom and running or discarding each item. + +* Morning teardown — Craig's, documented not automated + +Sentry never merges its own branch. In the morning Craig: + +1. Reviews the digest and the approval queue in =session-context.org=. +2. Runs or discards each approval-queue item. +3. Reviews the branch: =git log main..sentry/<date>-<host>= and the diff. +4. Squash-merges what he wants (=git switch main && git merge --squash sentry/<date>-<host>=, then one clean commit) or cherry-picks selectively. +5. Deletes the branch: =git branch -D sentry/<date>-<host>=. +6. Reverts any Emacs buffers still showing the pre-merge on-disk state (=emacs.md= buffer-revert caveat). + +A bad night is discarded by deleting one branch — nothing reached main, nothing was pushed. + +In a project that gitignores =.ai/=, the whole spine is untracked, so quiet fires produce no commits at all and =git log main..sentry/<date>-<host>= understates the night's activity. There the anchor's heartbeat list is the only record of what fired. Read the anchor, not just the log. (archangel, first live run 2026-07-21.) + +* Stop Sentry + +Trigger: "stop sentry" (and synonyms above). Sentry owns its own shutdown: + +1. *Cancel the schedule* — =CronList= to find the sentry job, then =CronDelete= its id. Under the self-rescheduling shape, also make sure the in-flight fire does not create its successor. Confirm no sentry job remains before moving on; a surviving job re-takes the working tree on its next fire. +2. *Release the single-runner lock* if this context holds it. +3. *Branch disposition* — offer, inline-numbered: + 1. Squash-merge the day's branch into main now (walk the morning teardown steps 3-5 interactively) + 2. Leave it named for later review (=sentry/<date>-<host>= stays; review at leisure) +4. *Approval queue* — offer to walk the queued items now, or carry them (they stay under the heading for whenever Craig reviews). + +Stopping sentry is the only way to reclaim the working tree mid-night. The entry gate fronts the handoff; stop-sentry ends it. + +* Wrap-up interaction + +=wrap-it-up.org= refuses while sentry is live: it detects the single-runner lock (=agent-lock status sentry-<project>= → held) and stops with "sentry is active — say 'stop sentry' first." The shutdown logic lives here, not in wrap-up; wrap-up carries only the one guard. + +* Common Mistakes + +1. *Running without the =:COMMIT_AUTONOMY:= grant* — sentry commits unattended; the marker is the entry ticket, and its absence is a hard stop, not a degrade. +2. *Starting from a dirty or red tree* — the entry gates exist because an unattended fire can't tell Craig's in-progress work from a regression. Answer the gate; don't bypass it. +3. *Committing onto main* — every writing pass commits to the daily =sentry/*= branch. A fire that finds HEAD off the sentry branch skips rather than commits. +4. *Running a =git= write against =~/org/roam=* — roam-sync is the only committer. Sentry edits the tree under the roam-write lock and triggers the sync; it never commits or pushes roam. +5. *A per-pass suite run* — the suite runs at entry (baseline) and conditionally at fire-end (only when a pass touched non-org files). Hourly per-commit runs all night is the anti-pattern the suite policy exists to prevent. +6. *Executing a judgment or destructive action unattended* — those queue for the morning with their exact command. The pass did its detection; Craig makes the call. The one sanctioned exception is pass 12's solo-task implementation, and only because it inherits work-the-backlog's full defer checklist (data-loss and irreversible actions defer, never execute) plus a premise-verifying review, and it commits to the branch rather than acting on anything live. +7. *A silent skip* — inside a working fire, every skip writes a digest line naming why; a missing pass with no line reads as "ran clean" when it didn't. The one exception is not a violation: an all-quiet fire collapses to a single =sentry at HH:MM: nothing= heartbeat instead of one skip line per pass — the heartbeat is the explicit "nothing to do" record, per the silent-until-signal policy. +8. *Degrading a pass to a reduced form* — a pass runs fully or skips. No half-passes. +9. *Letting an unmerged branch stall silently* — after two consecutive unmerged-branch skips, the persistent desktop notify fires. Don't suppress it. +10. *Merging sentry's branch automatically* — the morning teardown is Craig's. Sentry creates and commits; it never merges or deletes its own branch. + +* Living Document + +Sentry ships with eleven finding/hygiene passes, one opt-in implementation pass, and a deferred KB pass. The pass list, the interval default, the =:SENTRY_MAY_IMPLEMENT:= default, and the queue-vs-execute line for each pass are the knobs most likely to move with dogfooding. The implement pass especially is new (2026-07-24) and unproven at scale — watch the corrections signal (work-the-backlog's metric for autonomous commits later reverted or hand-fixed) before widening it past the projects that opt in. Fold in what the live trial surfaces — a pass that queues too eagerly, a probe that misfires, a digest line that wants more detail. Refine as the signal arrives. + +* History + +Built 2026-07-19 from the sentry spec (=docs/specs/2026-07-14-sentry-workflow-spec.org=, ID f6c51f27-d7a2-4b63-9ff9-5ba005a66dfb) — 10 decisions and 12 review findings resolved before the build. Phase 1 shipped the =agent-lock= helper (commit =a8b6cf4=); this file is Phase 2, the engine. Phase 3 reconciles the roam writers (=inbox.org=, =knowledge-base.md=) to acquire the roam-write lock and adds the =wrap-it-up.org= guard. diff --git a/working/sentry-arming-correction/2026-07-30-0739-from-work-correction-to-the-sentry-org-i-sent-you.org b/working/sentry-arming-correction/2026-07-30-0739-from-work-correction-to-the-sentry-org-i-sent-you.org new file mode 100644 index 0000000..c1676cc --- /dev/null +++ b/working/sentry-arming-correction/2026-07-30-0739-from-work-correction-to-the-sentry-org-i-sent-you.org @@ -0,0 +1,19 @@ +#+TITLE: Correction to the sentry.org I sent you twenty minutes ago — +#+SOURCE: from work +#+DATE: 2026-07-30 07:39:53 -0500 + +Correction to the sentry.org I sent you twenty minutes ago — pass 3 had Craig's ruling backwards, and this one is inherited from your canonical. + +Your canonical at claude-templates/.ai/workflows/sentry.org line 138 reads: 'Triage intake — mail and messenger sources excluded. Run triage-intake.org, loading only its non-mail, non-messenger source plugins (calendar, PR/ticketing). The mail and messenger plugins — cmail, any Gmail variant, Telegram, Signal, chat DMs — are never loaded by a sentry fire: Craig ruled 2026-07-21 that sentry doesn't check email or messengers.' + +Craig corrected that this morning. The rule is that sentry must never SEND via email or any messenger. It was never about reading. Reading, classifying and filing from every channel is fine and always was. + +Why this is worth fixing rather than leaving: as written, every sentry-capable project runs an overnight sweep that is blind to the channels Craig's work actually arrives through, and it gains nothing for it, because the risk was never inbound. It also produces a strange asymmetry the file does not acknowledge, where a manual triage sees everything and the unattended one sees a fraction, for no stated reason beyond the misremembered ruling. + +What the work copy now says. Pass 3 is retitled 'read everything, send nothing' and runs the full triage-intake.org engine across every active source plugin, mail and messengers included. The probe simplifies accordingly, since there is no longer an exclusion for a source to survive. Then the rule is stated explicitly: mail hygiene that changes only local state, mark-read, star and trash, is allowed because it sends nothing, while anything that emits words or state to another person or system queues for morning approval and never fires unattended — an email send, a Slack, Telegram or Signal message, a ticket comment or state move, a posted PR review, a calendar RSVP. When it is unclear whether an action is outbound, queue it. + +I left the old wording quoted in place rather than deleting it, because the difference between the two readings is the whole point and a future reader deserves to see which one was wrong. + +This supersedes the pass-3 paragraph in the copy I sent earlier today. That earlier note also flagged a step 7 correction (arm with CronCreate rather than /loop, since CronCreate fires inside the arming session and inherits MCP auth) which still stands, and it is what makes the full-triage pass possible at all. One knock-on: my earlier note said the exclusion was 'a choice rather than a wall' and told readers not to overturn it without Craig saying so. He has now said so, and that sentence is gone. + +Still worth the grep I mentioned before: triage-intake.org's auto mode carries the same headless-auth claim about detached schedules and is likely wrong for the same reason. diff --git a/working/sentry-arming-correction/2026-07-30-0739-from-work-sentry.org b/working/sentry-arming-correction/2026-07-30-0739-from-work-sentry.org new file mode 100644 index 0000000..9b40aae --- /dev/null +++ b/working/sentry-arming-correction/2026-07-30-0739-from-work-sentry.org @@ -0,0 +1,248 @@ +#+TITLE: Sentry — Overnight Hygiene Supervisor +#+AUTHOR: Craig Jennings +#+DATE: 2026-07-19 + +* Overview + +Sentry is a scheduled interval sweep (=CronCreate=, armed in and bound to the arming session) that keeps a project's hygiene current while Craig is away. Each fire walks a fixed list of passes — roam pull, inbox zero, triage (reads every channel, sends through none), todo cleanup, task audit, working-files hygiene, spec board, link integrity, git health, prep freshness, bug and refactor finding, and (opt-in) solo-task implementation — and commits each pass's writing to a throwaway daily branch. Nothing pushes. In the morning Craig reviews the branch, squash-merges what he wants, and deletes it. + +The design goal is a project that greets the morning already tidy, with every judgment call and every destructive action parked in an approval queue rather than executed unattended. Sentry does the mechanical sweeping; Craig does the deciding. + +This file is the engine. It owns the entry gates, the branch mechanics, the lock model, the per-fire pass runner, the digest and approval queue, the skip semantics, and the stop-sentry shutdown. The =agent-lock= helper (=.ai/scripts/agent-lock=) provides the locks. The passes reuse existing workflows (=inbox.org=, =triage-intake.org=, =clean-todo.org=, =task-audit.org=) under sentry's unattended contract. + +* When to Use This Workflow + +Craig arms sentry at the end of a session, with the machine left running, to have overnight hygiene done by morning. + +Triggers: + +- "start sentry", "run sentry", "arm sentry", "sentry mode" +- "let sentry watch this overnight", "keep this tidy overnight" +- "start sentry hourly", "start sentry every <interval>" (sets the fire interval) + +Stop trigger (see Stop Sentry below): + +- "stop sentry", "stand down sentry", "sentry off" + +Sentry is deliberately *not* auto-armed. Running it in a project is a per-project grant (the =:COMMIT_AUTONOMY:= marker) plus a deliberate launch with Craig at the terminal for the entry gates. + +* Prerequisite — the autonomy ticket + +Sentry commits unattended. =commits.md= gates commits on Craig's approval, so sentry needs standing, per-project authorization to run at all. Before anything else, read the project's =.ai/notes.org= Workflow State block for: + +: :COMMIT_AUTONOMY: yes + +If the marker is absent or not =yes=, decline to start and name the marker: + +: Sentry needs ":COMMIT_AUTONOMY: yes" in .ai/notes.org Workflow State to run — it commits unattended. Add it to grant, or run the hygiene passes by hand. + +No half-running mode: a project without the grant doesn't run sentry's read-only passes either. The grant is one line away, so this is a deliberate opt-in, not a barrier. + +A second, *independent* marker gates the solo-task implementation pass (pass 12): + +: :SENTRY_MAY_IMPLEMENT: yes + +=:COMMIT_AUTONOMY:= lets sentry commit its hygiene sweeps to the branch; =:SENTRY_MAY_IMPLEMENT:= additionally lets it implement solo, decision-free backlog tasks on the branch. The split exists because the two carry different morning costs: hygiene is a two-minute merge, implemented code is a review session. A project can run hygiene-only sentry without the implement pass, and most should until sentry has quiet weeks behind it. Absent =:SENTRY_MAY_IMPLEMENT:=, pass 12 skips; sentry still runs every other pass. Requires =:COMMIT_AUTONOMY:= alongside it — implementing implies committing. + +* Entry — interactive, with Craig present + +Craig types the sentry trigger, so the first moves run with him at the terminal. Do them in order; each gate that fails stops entry until Craig answers. + +1. *Autonomy ticket* — the prerequisite above. Absent → decline and stop. + +2. *Dirty-tree gate.* =git diff --quiet HEAD= (tracked modifications only; untracked and gitignored files never block — an inbox drop or scratch file is not in-progress work). If the tracked tree is dirty, describe what's dirty and offer, inline-numbered per =interaction.md=: + + 1. Finish the job — commit the in-progress work first (recommended if it's a coherent unit) + 2. Stash it — =git stash= and start sentry on a clean tree + 3. Roll back named changes — discard specific files (names them) + + Wait for an answer. Sentry can't start unattended from a dirty state; that's the point. + +3. *Green-suite gate.* Run the project's full suite (=make test=, or the project's equivalent — detect it). Read the output. If anything is red, describe the failures and offer to investigate before arming. The loop starts only on a green baseline, because every unattended fire measures itself against "did I break this?" and a pre-existing red poisons that check. + +4. *Prior sentry branch.* =git branch --list 'sentry/*'=. An unmerged =sentry/*= branch from a previous night means the morning review didn't happen. Surface it and offer to squash-merge or delete it now (Craig is present); don't stack a second sentry branch on the first. + +5. *Reconcile the project branch.* Fetch and fast-forward-only against upstream — the same reconcile =startup= runs: + + : git fetch --all --prune + : git rev-list --left-right --count @{u}...HEAD + + Zero-behind → continue. Behind-only and clean → =git merge --ff-only @{u}=. Diverged → surface to Craig (he's present); don't auto-resolve. + +6. *Create the daily branch.* From HEAD: + + : git switch -c "sentry/$(date +%F)-$(uname -n)" + + The host suffix (=uname -n=) stops a same-date collision between the two daily drivers. The working tree now sits on this branch overnight — the launch hands the repo to sentry until the morning merge. Reclaiming it mid-night means stopping sentry first (see Stop Sentry). Note the Emacs buffer-revert caveat to Craig if he has the repo open: files change on disk under him overnight, so buffers want reverting after the morning merge (see =emacs.md=). + +7. *Arm the schedule.* Use *=CronCreate=*, not =/loop=. Default hourly; Craig's "every <interval>" phrase overrides. The fire prompt is one sentry fire (the Pass Runner below), written so a fresh context can execute it — it names this file, so the fire re-reads the workflow rather than relying on a conversation it cannot see. + + Two shapes, both valid: + + - *Recurring* (simplest): one =CronCreate= with =recurring: true= and a cron expression at the interval. The single-runner lock below handles the overlap case, so a long fire never gets a second fire on top of it. Stop by deleting the job. + - *Self-rescheduling* (Craig's established practice): =recurring: false=, and the last step of each fire creates the next one-shot job. Serialization is then structural rather than lock-dependent, and the interval measures from end-of-fire instead of wall clock, so a slow fire doesn't compress the next gap. Stopping is simply not rescheduling. + + Pick an off-minute rather than =0= or =30= (=7 * * * *=, not =0 * * * *=). + + Confirm the arming in one line: mechanism, interval, branch name, project. + + *Three constraints that decide how sentry can be used, and they were wrong in this file until 2026-07-30:* + + - *=CronCreate= jobs are session-only and in-memory.* They are not written to disk and they vanish when the Claude session exits. Sentry therefore survives exactly as long as the session that armed it. Tell Craig this at arming time: closing the terminal ends sentry, and the branch is left wherever the last fire got to. + - *Fires run inside the arming session, so MCP auth is inherited.* This is why sentry's triage pass can reach Gmail, Slack, Linear and the calendars at all. An earlier version of this file claimed a detached schedule hits a headless-auth wall and prescribed =/loop= to avoid it; that reasoning applied to a *system* =cron= or =at= job spawning a fresh headless agent, and it does not apply to =CronCreate=. Proven in the work project overnight on 2026-07-28/29, where cron-driven triage sweeps ran mail, Slack, Linear and calendar reads for hours. + - *Recurring jobs auto-expire after seven days*, firing one last time before deletion. Irrelevant for an overnight run; it bounds anything longer. + + Inherited auth is what makes pass 3's full triage possible at all — see that pass for the read-everything, send-nothing rule. The constraint on sentry has always been outbound, never inbound. + +* The lock model + +Two locks, both served by =.ai/scripts/agent-lock= (names only; the helper owns the paths, which live on tmpfs under =$XDG_RUNTIME_DIR/agent-locks/=, host-local and cleared on reboot). + +*Single-runner lock* (=sentry-<project>=, where =<project>= is the repo-root basename: =basename "$(git rev-parse --show-toplevel)"= — the same derivation =wrap-it-up.org='s guard uses, so the two agree on the lock name). Each fire acquires it at fire start and releases it at fire end, and refreshes it between passes (the heartbeat, so a live fire's lock never ages past one pass). If the schedule fires again while a previous fire still holds it, the new fire's acquire fails and the fire skips with one digest line — no two fires run at once. (Under the self-rescheduling shape this cannot arise, since the next job is only created once the current fire ends; the lock is the belt-and-braces for the recurring shape.) The bounded wait is short (a few seconds); a live fire means defer, not queue. + +*Roam-write lock* (=roam-write=). A pass that edits a file under =~/org/roam= acquires it, runs =capture-guard --wait= (the human-capture layer stays underneath), edits the working tree, triggers =systemctl --user start roam-sync.service=, and releases. The lock spans only edit-plus-trigger. Sentry never runs =git= against =~/org/roam= — roam-sync stays the repo's only committer (the 2026-06-24 one-git-owner rule). Pass 1's =pull --ff-only= is the sole, read-only exception. + +Every reclaim of a stale lock surfaces in the digest — the helper prints the reclaim note, and the fire records it. A reclaim during a genuinely slow pass is possible, so it's never silent. + +* The Pass Runner — one contract per pass + +Each fire, after acquiring the single-runner lock and verifying branch state (below), walks the pass list in order. Every pass follows the same four-step contract: + +1. *Probe* — a cheap existence check for the pass's target (named per pass below). Absent → the pass is one skip line in the digest and nothing more. This is what makes the pass list portable: passes self-activate where their target exists and stay silent elsewhere, with zero per-project configuration. + +2. *Work* — run the pass under the unattended contract. Quick, solo, already-agreed mechanical actions execute. Anything destructive or requiring judgment does *not* execute — it appends to the morning-approval queue (what, why, the exact command or edit that fires on approval). A pass runs fully or not at all; there is no reduced-form pass. + +3. *Session-context entry* — a pass that does or queues work appends its digest line to the =session-context.org= Session Log (path resolved via =.ai/scripts/session-context-path=) before its commit, so a crash between them still leaves the trail. Per-pass lines for an all-quiet fire (every pass probe-skipped or no-op) are not written one by one — the fire collapses to a single heartbeat at fire-end (below), so an idle fire doesn't spray one skip line per pass. + +4. *Commit* — if the pass wrote to disk, commit it: =chore(sentry): <pass> — <what changed>=. One commit per writing pass. A probe-skip or a no-op pass writes nothing and commits nothing. + +Between passes, refresh the single-runner lock (=agent-lock refresh sentry-<project>=) — the heartbeat. + +** Branch-state verification (fire start, before the passes) + +After acquiring the lock, confirm the fire is safe to run: + +- *On the right branch* — HEAD is =sentry/<today>-<host>=. If the schedule was armed on a prior day and crossed midnight, the branch keeps the arming date; that's fine, morning teardown handles it. If HEAD is somehow *not* a sentry branch (an interrupted stop, a manual checkout), skip the whole fire with a digest line rather than committing onto main. +- *Clean of foreign changes* — =git diff --quiet HEAD= excluding the spine set (=session-context.org= / =session-context.d/=, resolved via =session-context-path=). Sentry's own spine writes must not trip this; a genuinely unexpected dirty tree (something outside the spine changed and wasn't committed by a prior pass) poisons the fire — skip it with a digest line, the next fire retries. + +* Unattended safety — skip, never degrade + +With no one at the terminal, any unsafe state makes the affected scope skip with one digest line, and the next fire retries. Unsafe states and their scope: + +- *Unexpected dirty tree* (non-spine) → skip the whole fire. +- *Lost or un-acquirable single-runner lock* → skip the fire (another fire holds it, or the helper is missing). +- *A pass's own precondition unmet* (its probe fails, or a dependency is dirty) → skip that pass only. +- *Red suite at fire-end* (see below) → the commits stay on the branch, flagged in the digest for morning review; the fire doesn't roll back. + +Skips are never silent and never partial. Inside a *working* fire, a pass line means the pass fully ran and a skip line names why it didn't. An *all-quiet* fire is not a silent skip either: its single =sentry at HH:MM: nothing= heartbeat is the explicit record that every pass found nothing, standing in for a wall of identical skip lines. The anti-silence rule targets a pass that hides work it should have surfaced; a quiet fire has surfaced that there was none. + +** Multi-day stall notification + +An unmerged prior =sentry/*= branch at fire start (the morning review never happened) skips the fire. After the *second consecutive* fire skipped for this reason, send one persistent desktop notification naming the project and branch: + +: sentry stalled: <branch> unmerged — merge or delete to resume + +Then repeat at most daily. Persistent notify matches the paging convention — it stays on screen until dismissed. A multi-day stall never stays silent. + +* The pass list (v1) + +In order. Each names its detection probe. A pass whose probe fails is one skip line. + +1. *Roam pull* — =git -C ~/org/roam pull --ff-only=. Probe: =~/org/roam= is a git clone. Skipped when the roam tree is dirty (roam-sync owns that case) or the clone is absent. Read-only and ff-only — the one narrow exception to "don't touch roam git," so later passes read a fresh tree. + +2. *Inbox zero* — run =inbox.org= roam mode under the no-approvals contract: quick+solo+agreed items execute, shared-asset and convention proposals park (prepared diff, =VERIFY= task, sender reply) in the approval queue. Edits to =~/org/roam/inbox.org= take the roam-write lock + =capture-guard=. Probe: the roam clone or a project =inbox/= exists. Tidying the shared roam inbox is allowed from *any* project session, work included — it's housekeeping on a shared resource, not a durable KB-node write, so the work-denylist doesn't gate it (=knowledge-base.md=). Never park it as a cross-project boundary crossing. + +3. *Triage intake — read everything, send nothing.* Run the full =triage-intake.org= engine, loading *every* active source plugin, mail and messengers included. Probe: the project has at least one active triage source — a project-specific plugin (=.ai/project-workflows/triage-intake.*.org=), or a non-empty =:TRIAGE_SOURCES:= declaration naming general plugins that exist. Mere presence of the template-synced general plugins does *not* activate the pass; a project that declares no sources probe-skips (see =docs/specs/2026-07-20-triage-source-activation-spec.org=). + + *The rule is about sending, not reading (Craig, corrected 2026-07-30).* Sentry must never *send* via email or any messenger. It may read, classify and file from every channel. This file previously recorded the 2026-07-21 ruling as "sentry doesn't check email or messengers" and had the pass load only non-mail, non-messenger plugins, which is a different and much weaker workflow: it left the overnight sweep blind to exactly the channels Craig's work arrives through, for no benefit, since the risk was never in the reading. + + So: mail hygiene that changes only local state — mark-read, star, trash — is allowed, because it sends nothing. Anything that emits words or state to another person or system queues for morning approval and never fires unattended: an email send, a Slack, Telegram or Signal message, a ticket comment or state move, a posted PR review, a calendar RSVP. When it is unclear whether an action is outbound, queue it. + +4. *Todo cleanup* — the =clean-todo.org= mechanics (hygiene pass + =--archive-done= + =--convert-subtasks=). Probe: a root =todo.org=. Note that =--archive-done= is not purely an org-file pass on its first run in a project: it creates =archive/task-archive.org= and appends a =.gitignore= entry, so it produces a real tracked-file commit and correctly trips the fire-end conditional suite. (archangel, first live run 2026-07-21.) + +5. *Task audit* — the *mechanical subset* of =task-audit.org= hourly (staleness counts, structural checks, cookie recomputation); the judgment half (priority regrades, consolidations, merge candidates) runs *once per night* and queues its findings rather than repeating them every fire. Probe: a root =todo.org=. A full audit every hour is too heavy and re-surfaces the same judgment calls all night. (takuzu, first live run 2026-07-21.) Factual staleness fixes that are unambiguous still execute. + +6. *Working-files hygiene* — flag =working/<slug>/= directories whose backing task is closed (a filing candidate per =working-files.md=). Probe: a =working/= directory exists. The filing itself queues (it's a judgment move). + +7. *Spec status board* — the =docs-lifecycle= grep for spec keywords, surfacing any =DOING= spec whose bound build parent is closed. Probe: =docs/specs/= exists. + +8. *Link integrity* — broken =file:= links in the project's org files, via =lint-org.el=. Probe: =lint-org.el= present. Report-only into the digest; no unattended rewrites. + +9. *Git health* — uncommitted drift, unpushed commits on other branches, stale branches, main-behind-origin. Probe: =.git=. Report into the digest. + +10. *Prep + symlink freshness* — stale daily-prep docs, broken symlinks. Probe: the prep dir / symlinks exist (work and home only, in practice). + +11. *Bug and refactor finding* — hunt for real bugs and worthwhile refactoring opportunities in the project's codebase: static analysis (=shellcheck= for shell, the project's own linters for its languages), config sanity checks, plus one targeted code-reading area per fire. Rotate the area across fires and name it in the digest, so coverage accumulates over a night instead of re-reading the same corner. Randomized property sweeps (generate-and-verify against an engine's own invariants) are good quiet-fire work here, reaching past a frozen test corpus. Expect the pass to go honestly quiet after the first few fires find the standing defects; a quiet hunt is a result, not a failure. (takuzu, first live run 2026-07-21: three real fixes in the first four fires, then quiet.) This pass does *not* run the test suite — the entry baseline already ran it, and re-running it hourly is anti-pattern 5; read the entry result instead. Probe: the project carries a codebase — source under version control beyond its org and tooling files. File each verified bug as a graded task in =todo.org= per the severity × frequency matrix (=todo-format.md=), and each refactoring opportunity as a =:refactor:= task, deduped against existing tasks; an unverifiable suspicion is a digest line, not a task. *Find, never fix in this pass* — the finding files a task and stops. A fix happens only in the opt-in implementation pass below, and only after the finding is a filed task that pass then re-verifies from scratch (see the premise rule there). A freshly-found "bug" can be a misread — one was filed and retracted two fires apart on 2026-07-23 — so the file-then-verify-then-fix pipeline is deliberate: the task is the checkpoint, not a same-breath fix. (Added at Craig's order 2026-07-21, first dogfooded in dotfiles; refactor-finding added 2026-07-24.) + +12. *Solo-task implementation (opt-in — =:SENTRY_MAY_IMPLEMENT:=)* — work the backlog's solo, decision-free tasks on the branch. Probe: =.ai/notes.org= Workflow State carries =:SENTRY_MAY_IMPLEMENT: yes= *and* the project holds =:COMMIT_AUTONOMY:= (the implement pass commits). Absent the marker, skip — this pass is off by default, because it turns the morning from a two-minute merge into a code review, and that's the project owner's call. When on: invoke =work-the-backlog.org= under its unattended-loop contract (no pre-flight Q&A — there's no Craig overnight), eligibility =TODO= + =:solo:=, with the defer checklist deciding act-vs-file. The overnight-only tightening: only the *ready* bucket implements (clears every checklist item with zero open decisions); a task needing even one quick decision defers to a =VERIFY= rather than guessing, exactly as the loop caller already does. Commit each logical change to the sentry branch; *never push* — the morning review and merge is the gate, same as every other pass. The full quality bar holds (TDD, suite green before each commit, =/review-code=, =/voice=), and =/review-code= here runs the *premise check first*: reproduce the bug or confirm the problem is real before judging the diff. The review is the fact-checker that a filed claim never got, and it is what makes fixing-on-a-branch safe (Craig, 2026-07-24). A task that fails its premise check is not implemented — the finding was wrong, and that outcome is a digest line, not a commit. (Added at Craig's direction 2026-07-24: overnight implement-on-branch, gated and never-pushed.) + +(KB lesson promotion — the pass the original proposal listed eleventh — is deferred to vNext. An unattended judgment pass writing to the shared knowledge base waits until sentry has quiet weeks behind it and a designed detection heuristic. See the filed lesson-detection-heuristic task.) + +* Fire-end — conditional suite, then the digest commit + +After the passes: + +1. *Conditional suite run.* If any pass this fire modified files *outside* the org/spine set (a code-touching pass, rare but possible via fixtures), run the full suite once. A green run confirms the fire's commits are safe; a red run flags the digest for morning review — the commits stay on the branch (nothing is pushed, so the morning gate catches it). No per-pass suite runs: the entry run is the green baseline, and hourly per-commit runs would turn a seconds-long fire into minutes all night. Fires that only touched org/spine files skip this. + +2. *Heartbeat or digest, then commit.* Decide quiet vs working. A *quiet* fire — every pass probe-skipped or no-op, nothing added to the approval queue — writes a single heartbeat line to the Session Log, =sentry at HH:MM: nothing= (HH:MM local, from =date=), and no per-pass digest block. A *working* fire — any pass ran, wrote, or queued — writes its full per-pass digest block. Then commit any accumulated spine writes in one sweep: =chore(sentry): digest — <date> <time> fire= for a working fire, =chore(sentry): heartbeat — <date> <time>= for a quiet one, so even a quiet fire leaves a clean tree for the next branch-state check (where the spine is untracked, the mirror-only case, there is nothing to commit and the heartbeat line stays in the working-tree anchor). This is the silent-until-signal policy (see =docs/specs/2026-07-20-silent-until-signal-monitors-spec.org=): an all-quiet night collapses from a wall of no-op digests to a list of one-line heartbeats, while a fire that actually did or queued something still writes the full record. + +3. *Release the single-runner lock.* + +* The digest and the approval queue + +*Digest.* A *working* fire appends its block to the =session-context.org= Session Log (the spine the fire already writes), so it survives a crash, rides the session archive, and is on screen in the running session. One block per working fire: the timestamp, then one line per pass (ran + what, or skipped + why), plus any lock reclaim notes. A *quiet* fire (nothing done or queued) writes no block — just the one heartbeat line =sentry at HH:MM: nothing= (the silent-until-signal policy). The per-pass block is a working-fire artifact; it still carries one line per pass so a real skip inside a working fire is never hidden. + +*Approval queue.* Destructive and judgment actions accumulate under one heading in the same file — =* Sentry approval queue (<date>)= — newest last. Each item carries three things: *what* (the action), *why* (what triggered it), and the *exact command or edit* that fires on approval. The morning review is Craig reading this heading top to bottom and running or discarding each item. + +* Morning teardown — Craig's, documented not automated + +Sentry never merges its own branch. In the morning Craig: + +1. Reviews the digest and the approval queue in =session-context.org=. +2. Runs or discards each approval-queue item. +3. Reviews the branch: =git log main..sentry/<date>-<host>= and the diff. +4. Squash-merges what he wants (=git switch main && git merge --squash sentry/<date>-<host>=, then one clean commit) or cherry-picks selectively. +5. Deletes the branch: =git branch -D sentry/<date>-<host>=. +6. Reverts any Emacs buffers still showing the pre-merge on-disk state (=emacs.md= buffer-revert caveat). + +A bad night is discarded by deleting one branch — nothing reached main, nothing was pushed. + +In a project that gitignores =.ai/=, the whole spine is untracked, so quiet fires produce no commits at all and =git log main..sentry/<date>-<host>= understates the night's activity. There the anchor's heartbeat list is the only record of what fired. Read the anchor, not just the log. (archangel, first live run 2026-07-21.) + +* Stop Sentry + +Trigger: "stop sentry" (and synonyms above). Sentry owns its own shutdown: + +1. *Cancel the schedule* — =CronList= to find the sentry job, then =CronDelete= its id. Under the self-rescheduling shape, also make sure the in-flight fire does not create its successor. Confirm no sentry job remains before moving on; a surviving job re-takes the working tree on its next fire. +2. *Release the single-runner lock* if this context holds it. +3. *Branch disposition* — offer, inline-numbered: + 1. Squash-merge the day's branch into main now (walk the morning teardown steps 3-5 interactively) + 2. Leave it named for later review (=sentry/<date>-<host>= stays; review at leisure) +4. *Approval queue* — offer to walk the queued items now, or carry them (they stay under the heading for whenever Craig reviews). + +Stopping sentry is the only way to reclaim the working tree mid-night. The entry gate fronts the handoff; stop-sentry ends it. + +* Wrap-up interaction + +=wrap-it-up.org= refuses while sentry is live: it detects the single-runner lock (=agent-lock status sentry-<project>= → held) and stops with "sentry is active — say 'stop sentry' first." The shutdown logic lives here, not in wrap-up; wrap-up carries only the one guard. + +* Common Mistakes + +1. *Running without the =:COMMIT_AUTONOMY:= grant* — sentry commits unattended; the marker is the entry ticket, and its absence is a hard stop, not a degrade. +2. *Starting from a dirty or red tree* — the entry gates exist because an unattended fire can't tell Craig's in-progress work from a regression. Answer the gate; don't bypass it. +3. *Committing onto main* — every writing pass commits to the daily =sentry/*= branch. A fire that finds HEAD off the sentry branch skips rather than commits. +4. *Running a =git= write against =~/org/roam=* — roam-sync is the only committer. Sentry edits the tree under the roam-write lock and triggers the sync; it never commits or pushes roam. +5. *A per-pass suite run* — the suite runs at entry (baseline) and conditionally at fire-end (only when a pass touched non-org files). Hourly per-commit runs all night is the anti-pattern the suite policy exists to prevent. +6. *Executing a judgment or destructive action unattended* — those queue for the morning with their exact command. The pass did its detection; Craig makes the call. The one sanctioned exception is pass 12's solo-task implementation, and only because it inherits work-the-backlog's full defer checklist (data-loss and irreversible actions defer, never execute) plus a premise-verifying review, and it commits to the branch rather than acting on anything live. +7. *A silent skip* — inside a working fire, every skip writes a digest line naming why; a missing pass with no line reads as "ran clean" when it didn't. The one exception is not a violation: an all-quiet fire collapses to a single =sentry at HH:MM: nothing= heartbeat instead of one skip line per pass — the heartbeat is the explicit "nothing to do" record, per the silent-until-signal policy. +8. *Degrading a pass to a reduced form* — a pass runs fully or skips. No half-passes. +9. *Letting an unmerged branch stall silently* — after two consecutive unmerged-branch skips, the persistent desktop notify fires. Don't suppress it. +10. *Merging sentry's branch automatically* — the morning teardown is Craig's. Sentry creates and commits; it never merges or deletes its own branch. + +* Living Document + +Sentry ships with eleven finding/hygiene passes, one opt-in implementation pass, and a deferred KB pass. The pass list, the interval default, the =:SENTRY_MAY_IMPLEMENT:= default, and the queue-vs-execute line for each pass are the knobs most likely to move with dogfooding. The implement pass especially is new (2026-07-24) and unproven at scale — watch the corrections signal (work-the-backlog's metric for autonomous commits later reverted or hand-fixed) before widening it past the projects that opt in. Fold in what the live trial surfaces — a pass that queues too eagerly, a probe that misfires, a digest line that wants more detail. Refine as the signal arrives. + +* History + +Built 2026-07-19 from the sentry spec (=docs/specs/2026-07-14-sentry-workflow-spec.org=, ID f6c51f27-d7a2-4b63-9ff9-5ba005a66dfb) — 10 decisions and 12 review findings resolved before the build. Phase 1 shipped the =agent-lock= helper (commit =a8b6cf4=); this file is Phase 2, the engine. Phase 3 reconciles the roam writers (=inbox.org=, =knowledge-base.md=) to acquire the roam-write lock and adds the =wrap-it-up.org= guard. diff --git a/working/sync-model-revert/2026-07-30-1820-from-.emacs.d-distribution-failure-on-the-loadchats.org b/working/sync-model-revert/2026-07-30-1820-from-.emacs.d-distribution-failure-on-the-loadchats.org new file mode 100644 index 0000000..ac90fef --- /dev/null +++ b/working/sync-model-revert/2026-07-30-1820-from-.emacs.d-distribution-failure-on-the-loadchats.org @@ -0,0 +1,25 @@ +#+TITLE: Distribution failure on the loadChats fix — the canonical is +#+SOURCE: from .emacs.d +#+DATE: 2026-07-30 18:20:51 -0500 + +Distribution failure on the loadChats fix — the canonical is right, but it has reached almost nobody. Craig is seeing 'telega server died' on every triage intake run, and there are eight telega-server SIGSEGVs on ratio today with the log still ending in the identical 'Unexpected char m' assertion. + +The fix is not at fault. Two independent breaks in the chain: + +1. WORK HAS NEVER RE-SYNCED. Their session started Tue Jul 28 09:02, and bff0138 landed at 14:07 the same day. Template sync runs at STARTUP ONLY, so a long-running session cannot receive a mid-session fix to a rulesets-owned file. Their copy still has bare 'main at both call sites. They are almost certainly the source of every crash Craig is seeing. I have sent them the patch directly with instructions to apply it now rather than wait for a restart. + +2. YOUR TREE IS CURRENTLY BLOCKING THE SYNC FOR EVERYONE ELSE. right now: + + MM claude-templates/.ai/workflows/sentry.org + + The startup guard skips all three rsyncs when anything under the synced template paths is dirty. So even home, which started fresh this morning at 08:09 — after the fix — did not receive it. They are safe only because they hand-patched their own copy on 2026-07-28. Committing or stashing that sentry.org edit unblocks propagation for every project's next startup. + + Also: 43a4cf7 is unpushed. Not urgent for local rsync, which reads the working tree, but velox will not see it. + +THE SYSTEMIC PART, WHICH I THINK IS THE REAL FINDING. A correctness fix to a synced file has no path to a running session. Startup-only sync means the blast radius of any such fix is 'projects that happen to start after it lands, while your tree happens to be clean'. For a cosmetic template change that is fine. For one that stops an agent corrupting a service on every run, it is not — this one had a two-day tail and needed a human to notice the symptom. + +Worth considering, in rough order of cost: a mid-session freshness check that compares a hash of the synced paths and warns; a targeted-file escape hatch for correctness fixes; or narrowing the dirty-guard so an unrelated dirty file blocks only that file rather than all three rsyncs. The last one alone would have gotten home the fix this morning. + +Not proposing a specific patch — this is your area and you will see the tradeoffs better than I will. Flagging it because I only found it by reading four projects' copies side by side, and nothing in the system would have surfaced it on its own. + +On my side I copied just the telegram file across rather than running the rsync, so I did not pull your in-flight sentry.org edit. diff --git a/working/sync-model-revert/2026-07-30-1829-from-work-the-telega-loadchats-fix-regressed-in.org b/working/sync-model-revert/2026-07-30-1829-from-work-the-telega-loadchats-fix-regressed-in.org new file mode 100644 index 0000000..56182c9 --- /dev/null +++ b/working/sync-model-revert/2026-07-30-1829-from-work-the-telega-loadchats-fix-regressed-in.org @@ -0,0 +1,15 @@ +#+TITLE: The telega loadChats fix regressed in this project, and the +#+SOURCE: from work +#+DATE: 2026-07-30 18:29:42 -0500 + +The telega loadChats fix regressed in this project, and the mechanism is one your sync model should probably account for. + +Symptom: .ai/workflows/triage-intake.telegram.org here was back to (telega--loadChats 'main) at both call sites today, and it crashed telega-server on five of my six auto-triage sweeps this evening (journalctl coredumps at 16:24, 17:36, 17:57, 18:06, 18:16). .emacs.d caught it and sent the alert. + +The mechanism is what matters. Our session log records that we patched both call sites locally on 2026-07-28 and sent the canonical fix to you. The startup sync rsyncs .ai/workflows/ with --delete, so at our next startup the local patch was replaced by whatever the canonical held at that moment, and ours evidently synced while the canonical was still pre-fix. Net effect: a file we had already fixed silently reverted to broken, while our own log kept saying it was patched. It stayed that way for two days. + +The known failure mode was 'a long-running session never re-syncs, so a mid-session fix cannot reach it'. This is the mirror of it and it is worse, because the reverting session looks up to date. Worth a line in the cross-project rule: a local patch to a rulesets-owned file is not merely a stopgap that eventually gets superseded, it is a stopgap that can be silently rolled back to the broken version, so the only durable record that the fix happened is in the canonical. + +Two smaller notes. The canonical should carry the dead-server signal .emacs.d proposed, if it does not already: ending that emacsclient payload with (if (and (fboundp 'telega-server-live-p) (telega-server-live-p)) 'loaded 'server-died) is what lets a scan distinguish a dead server from a quiet account. Without it a crashed scan reports clean, which is exactly how five of my sweeps tonight reported healthy Telegram coverage while the server was dying under them. + +And a correction worth propagating if the plugin still says otherwise: the chat count is not a truncation tell. The pre-fix runs and today's patched run both load 20 chats here. Whatever the earlier 19-versus-truncation reasoning concluded, the count was never the signal. diff --git a/working/sync-model-revert/2026-07-30-1832-from-.emacs.d-correction-and-escalation-on-the-sync.org b/working/sync-model-revert/2026-07-30-1832-from-.emacs.d-correction-and-escalation-on-the-sync.org new file mode 100644 index 0000000..7ce4e9d --- /dev/null +++ b/working/sync-model-revert/2026-07-30-1832-from-.emacs.d-correction-and-escalation-on-the-sync.org @@ -0,0 +1,17 @@ +#+TITLE: Correction and escalation on the sync finding I sent you at +#+SOURCE: from .emacs.d +#+DATE: 2026-07-30 18:32:35 -0500 + +Correction and escalation on the sync finding I sent you at 18:20 — work's version is sharper and changes what needs fixing. + +I told you the failure mode was 'a correctness fix to a synced file has no path to a running session'. True, but it is the milder half. Work reports the worse one, from their own experience: + +The startup rsync runs .ai/workflows/ with --delete. So a local fix to a rulesets-owned file is silently REVERTED at the next startup by whatever the canonical says at that moment. A project that does everything right — hits the bug, diagnoses it, patches locally, records the patch in its own session log, restarts — comes back running the broken version, with its log still asserting it was fixed. That is what happened to them, and it is why this survived two days while three projects believed it was handled. + +So the hazard is not only 'the fix cannot reach you'. It is 'the sync can take your working fix away and leave no trace at the point of loss'. The local edit looks durable for exactly as long as nobody restarts. + +That reframes the mitigation. A freshness check or a targeted escape hatch addresses my version. Neither addresses theirs, because the loss happens at a moment the project considers routine and successful. Something closer to: the rsync noticing that the file it is about to overwrite differs from both the canonical and the last-synced state, and saying so before deleting. Or the cross-project rule stating outright that a local edit to a rulesets-owned file survives only until the next startup, so the inbox-send to rulesets is not a courtesy but the only durable step. + +I am not proposing the patch. Flagging that my first framing understated it, and that work's is the one to design against. + +One caveat I gave them too: their tmux session predates the canonical fix, so I cannot reconstruct which sync reverted which patch. The mechanism stands on its own; the specific timeline I could not verify. diff --git a/working/sync-model-revert/2026-07-30-1911-from-.emacs.d-propagation-verified-end-to-end-from-a.org b/working/sync-model-revert/2026-07-30-1911-from-.emacs.d-propagation-verified-end-to-end-from-a.org new file mode 100644 index 0000000..d30bd56 --- /dev/null +++ b/working/sync-model-revert/2026-07-30-1911-from-.emacs.d-propagation-verified-end-to-end-from-a.org @@ -0,0 +1,23 @@ +#+TITLE: Propagation verified end to end from a consuming project. Yo +#+SOURCE: from .emacs.d +#+DATE: 2026-07-30 19:11:18 -0500 + +Propagation verified end to end from a consuming project. You cannot test this from inside rulesets, so here is the confirmation. + +Ran the guarded startup sync here with your tree in its current state: rulesets clean under all three synced paths, zero unpushed, my branch level with upstream. Result SYNCED, and a recursive diff of .ai/workflows/ against claude-templates now returns nothing. The chain works. + +WHAT THE BLOCKED WINDOW ACTUALLY COST, measured rather than estimated. Before that sync, five workflow files in this project alone were stale against the canonical: + + helper-mode.org + no-approvals.org + sentry.org + work-the-backlog.org + wrap-it-up.org + +So the telegram plugin was the one with teeth, but it was not alone — it was the one whose staleness happened to crash a service loudly enough to notice. Four others drifted silently and would have kept drifting. That is the part I would hold onto when you and Craig design this: the loud failure is the exception, and the ordinary case is a project quietly running last week's workflows with nothing anywhere saying so. + +Also confirms your own account of the window. Home starting clean at 08:09 and still missing the fix was not a one-file anomaly; every project that started today got none of these five. + +I verified your canonical claims rather than taking them: the corrected loadChats form is present at all three sites in the plugin I now hold, and the file matches yours byte for byte after sync. Not doubting you — just that 'I have it now' is a stronger statement from this side than 'it is in the canonical' is from yours, and you were owed the stronger one. + +Nothing needed back. Good luck with the design session; the narrowing plus a last-synced record still reads right to me, and work's framing is the one that needs the record. diff --git a/working/sync-model-revert/2026-07-31-0816-from-.emacs.d-read-and-the-inversion-sounds-right-to.org b/working/sync-model-revert/2026-07-31-0816-from-.emacs.d-read-and-the-inversion-sounds-right-to.org new file mode 100644 index 0000000..b9a3faa --- /dev/null +++ b/working/sync-model-revert/2026-07-31-0816-from-.emacs.d-read-and-the-inversion-sounds-right-to.org @@ -0,0 +1,9 @@ +#+TITLE: Read, and the inversion sounds right to me from this end. +#+SOURCE: from .emacs.d +#+DATE: 2026-07-31 08:16:38 -0500 + +Read, and the inversion sounds right to me from this end. + +The one thing I would add to the manifest design: the third state you named, locally edited and diverging, is not rare here. This project has legitimately patched rulesets-owned files as stopgaps more than once, and the propagation rule tells us to do exactly that. So back-up-overwrite-and-report will fire on real work, not just on accidents, and the report is what has to be good. The backup path alone is thin. What I would want in it is the diff, so I can tell in one look whether the canonical already carries my patch or whether my change just got thrown away and needs re-sending. + +No reply needed on this one either. diff --git a/working/triage-declaration-model/2026-07-30-1733-from-work-reciprocal-to-the-triage-sources-defect.org b/working/triage-declaration-model/2026-07-30-1733-from-work-reciprocal-to-the-triage-sources-defect.org new file mode 100644 index 0000000..1041c8a --- /dev/null +++ b/working/triage-declaration-model/2026-07-30-1733-from-work-reciprocal-to-the-triage-sources-defect.org @@ -0,0 +1,21 @@ +#+TITLE: Reciprocal to the :TRIAGE_SOURCES: defect you flagged today, +#+SOURCE: from work +#+DATE: 2026-07-30 17:33:44 -0500 + +Reciprocal to the :TRIAGE_SOURCES: defect you flagged today, and a widening of it that Craig raised in the same breath. + +You caught work reading his personal mail (cmail). Fixed here: cmail dropped from .ai/notes.org Workflow State with the reason written in, telegram kept deliberately (Kostya and Vrezh reach him there, so it carries real work traffic despite sitting in the general plugin set), personal-calendar left in place and marked under review since a work sweep uses it to see conflicts against work meetings. + +I also had to re-arm an auto-triage cron I had started twenty minutes earlier, because I baked the source list into the job prompt rather than having it read :TRIAGE_SOURCES: at run time. That is a general trap worth naming in the declaration spec: a corrected declaration does nothing for a job already running with a copy of the old list. + +The wider requirement, Craig's words on 2026-07-30: 'This is a new-ish decision, and I was okay with it. It's just with all the talk of CUI, I have to do this with every other project too - work email, calendar, etc. are off limits.' + +So the rule is bidirectional, and the reverse direction is the one carrying compliance weight. Work skipping personal mail is privacy and tidiness. Personal and tooling projects reading WORK email, work calendar, work Slack, or work Drive is a CUI exposure question, because those channels carry controlled information into projects with no basis to hold it. That reaches home, .emacs.d, dotfiles, and any project whose declaration or plugin set can touch a work account. + +Two suggestions for the per-project declaration model you are speccing, offered rather than asserted since the model is yours: + +1. Work-account sources probably need to be denied by default and named explicitly to enable, rather than merely absent-by-default. The failure you caught was silent: an over-broad declaration looks identical to a correct one until someone reads which account sits behind the plugin name. + +2. The declaration should be read at run time by whatever consumes it, and any long-running job that caches it is a defect. Worth stating in the spec so it is not rediscovered per project. + +I have not touched any other project's declaration from here, per the cross-project rule. Flagging so the sweep happens where it belongs. diff --git a/working/triage-telegram-down-launch/note-from-emacsd.txt b/working/triage-telegram-down-launch/note-from-emacsd.txt deleted file mode 100644 index 209aa24..0000000 --- a/working/triage-telegram-down-launch/note-from-emacsd.txt +++ /dev/null @@ -1,27 +0,0 @@ -FOLLOW-UP / CORRECTION to my earlier triage-intake.telegram.org fix (inbox 2026-07-24-1723). Both affected projects (work + home) replied with reproductions, and the root cause is NOT the missing setq — it's a behavioral bug the plugin's wording allowed. Attaching the re-edited workflow file; please take this version, not the setq-only one. The setq fix is still included and correct; this adds the real fix on top. - -WHAT ACTUALLY BIT WORK AND HOME (both independently, same failure) - -The telegram source, on finding telega down/unloaded — its NORMAL entry state — reported "SCAN FAILED: telegram — not loaded" (work) or a silent SKIP / blind scan (home), INSTEAD OF running Step 1 to start it. Neither hit the segfault path. Verbatim from work's digest: - - ⚠ SCAN FAILED: telegram — telega isn't loaded in the running Emacs daemon, so this sweep is blind on Telegram. - -Work then ran the numbered Step 1 verbatim as a reproduction: down → (telega t) → server live (run open listen connect stop) → telega--loadChats → 18 chats. So the recovery IS Step 1; (telega t) both loads the package and starts the docker server. The sessions simply didn't run it — they treated "down" as "failed/skip." - -WHY THE WORDING ALLOWED IT - -The Quick Reference said "never skips because the server is down" (good), but the closing paragraph said "If any lifecycle step fails (docker image missing, server crash, daemon unreachable), the sweep reports it as SCAN FAILED." An agent conflates "server is down" with "a lifecycle step failed" → SCAN FAILED → blind sweep, without ever attempting the launch. Two agents made exactly this read. - -THE FIX (in the attached file) - -1. Added a prominent directive right after the Quick Reference intro: DOWN / not-loaded is the TRIGGER to launch, never a reason to skip or fail. (telega t) loads AND starts. SCAN FAILED is reserved for a launch that was ATTEMPTED and did not reach Ready. The :ENABLED: guard tests whether telega is INSTALLED (fboundp), not whether the server is up; a down server never disables the source. -2. Reworded the closing SCAN FAILED paragraph to say the failure rule applies only AFTER the launch was attempted — a pre-launch down state means "run Step 1," not "SCAN FAILED" — and noted a blind sweep is worse than a clean failure because it hides real unread behind a false all-clear. -3. Kept the setq fix in Step 1 (latent segfault guard; both projects confirmed it's real but was NOT the cause since the daemon reads telega-use-docker t). - -SECONDARY FINDING — ENGINE, not this plugin (your call) - -Work reported: "The marker still advanced, which is its own smell — a SCAN FAILED source shouldn't silently advance the sentinel." That's engine behavior in triage-intake.org (the per-source last-run/anchor advance), not the telegram plugin — telegram is :ANCHOR: none, yet something advanced. Worth a look: a source that reports SCAN FAILED advancing its cursor means the next sweep thinks it already covered that window, compounding the blind-sweep hole. I did not touch the engine; flagging for your judgment. - -STILL UNRESOLVED, for the record: home carries an older data point (its telega bug task, 2026-07-16) where a launch WITH the setq present returned 'started but server-live-p stayed nil and no container appeared — a launch failure not explained by any of the above. If that's since fixed by the current v1.2.0 image reaching Ready, it's moot; noting it in case the crashing recurs. - -No reply needed unless you disagree. diff --git a/working/triage-telegram-down-launch/note-superseded-1723.txt b/working/triage-telegram-down-launch/note-superseded-1723.txt deleted file mode 100644 index 7c54ede..0000000 --- a/working/triage-telegram-down-launch/note-superseded-1723.txt +++ /dev/null @@ -1,22 +0,0 @@ -Fix for a defect in triage-intake.telegram.org: the numbered Step 1 was missing the mandatory `(setq telega-use-docker t)` that the plugin's own Quick Reference and SEGFAULT gotcha both require. Attached is the edited workflow file (.ai/workflows/triage-intake.telegram.org) — please take it into the canonical at claude-templates/.ai/workflows/. - -THE DEFECT - -The plugin contradicts itself across three places: -- Quick Reference (line 35): `emacsclient -e "(progn (setq telega-use-docker t) (telega t) 'started)"` — has the setq. -- SEGFAULT gotcha (line ~170): "docker mode stays mandatory (telega-use-docker = t; the setq before (telega t) is still the right defense)". -- Numbered Step 1 (lines 91-93): `(progn (unless (...live-p) (telega t)) 'started)` — NO setq. - -telega-use-docker defaults to nil. In native (non-docker) mode the dockerized-vs-native tdlib difference is exactly the SEGFAULT the gotcha documents (exit 139). A session following the numbered Step 1 literally, on a daemon where nothing had already forced telega-use-docker to t, starts telega native and crashes the server — which the engine reports as SCAN FAILED at the top of the summary. Both of Craig's personal projects that use the telegram source (work and home) reported triage-intake failing. - -THE FIX - -Added `(setq telega-use-docker t)` as the first form in Step 1's progn, before the `(unless ... (telega t))`, with a comment pointing at the gotcha. Now Step 1 matches the Quick Reference. Minimal, wording/robustness only; no behavior change on a daemon that already had docker mode on. - -IMPORTANT CAVEAT — this is a real defect but NOT a confirmed root cause. I could not reproduce the original failure: Craig doesn't remember the symptom ("it was much earlier"), and his .emacs.d daemon currently reads telega-use-docker t (via .emacs.d's telega-config `:custom`), so on his machine right now the missing setq may have been moot. The fix removes one genuine failure mode that matches the reported symptom; whether it was THE cause is unconfirmed. I've asked work and home for their actual error via their inboxes; if they come back with something else (e.g. the recent :TRIAGE_SOURCES: gating change 4d87f35, or a different source), I'll send a follow-up. - -Two things worth your judgment on the canonical: -1. The stale note at line 37 ("Craig's daemon currently has telega-use-docker nil") is now false on .emacs.d — telega-config sets it t. Consider softening it to "the daemon's default is nil unless an Emacs-config :custom forces it," since the workflow syncs to machines/daemons without that config. -2. If the daemon reliably has docker mode on everywhere telega runs, this whole class is belt-and-braces — but Step 1 contradicting the Quick Reference is a defect regardless, and the belt is cheap. - -No reply needed unless you disagree with the fix. diff --git a/working/triage-telegram-down-launch/proposed.diff b/working/triage-telegram-down-launch/proposed.diff deleted file mode 100644 index 72b9cd4..0000000 --- a/working/triage-telegram-down-launch/proposed.diff +++ /dev/null @@ -1,57 +0,0 @@ ---- claude-templates/.ai/workflows/triage-intake.telegram.org 2026-07-09 13:57:29.819324933 -0500 -+++ working/triage-telegram-down-launch/triage-intake.telegram.org.proposed 2026-07-24 17:26:36.349127827 -0500 -@@ -30,6 +30,20 @@ - unless Craig has Telegram open in Emacs. The scan therefore runs the full - lifecycle every time, never skips because the server is down: - -+⚠ *DOWN / not-loaded is the TRIGGER to launch, never a reason to skip or fail.* -+This is the exact mistake two projects (work + home, 2026-07-24) made: they -+probed telega, saw =(telega-server-live-p)= nil or telega not =featurep=, and -+reported =SCAN FAILED: telegram — not loaded= or a silent SKIP — a *blind* -+sweep — instead of running Step 1 to start it. A down or unloaded telega is the -+normal entry state; =(telega t)= both LOADS the package and STARTS the docker -+server (work confirmed: down → =(telega t)= → Ready, 18 chats). So the plugin -+MUST run Step 1's launch whenever telega is down/unloaded, wait for Ready, then -+scan. =SCAN FAILED= is reserved for a launch that was actually ATTEMPTED and did -+not reach Ready (image missing, server crash on start, daemon unreachable) — -+never for the pre-launch down state itself. The =:ENABLED:= guard above tests -+whether telega is INSTALLED (=fboundp=), not whether the server is up; a down -+server never disables the source. -+ - 1. Record prior state: TELEGA_WAS_RUNNING via (telega-server-live-p). - 2. Launch (only if not running): - emacsclient -e "(progn (setq telega-use-docker t) (telega t) 'started)" -@@ -48,10 +62,13 @@ - Verify: telega-server-live-p → nil, no zevlg/telega-server container in - docker ps. If Craig had it running, leave it untouched. - --If any lifecycle step fails (docker image missing, server crash, daemon --unreachable), the sweep reports it as SCAN FAILED at the top of the summary --per the engine's failure rule — never as a silent skip. Craig gets real --traffic here. -+If any lifecycle step fails *after the launch was attempted* (docker image -+missing, server crash on start, daemon unreachable, Ready never reached), the -+sweep reports it as SCAN FAILED at the top of the summary per the engine's -+failure rule — never as a silent skip. This does NOT cover the ordinary -+pre-launch down state: a down server means "run Step 1," not "SCAN FAILED." -+Craig gets real traffic here, so a blind sweep that skipped the launch is worse -+than a clean failure — it hides real unread messages behind a false all-clear. - - ** Scan - -@@ -88,7 +105,15 @@ - # `(telega t)` starts without popping the root buffer. Docker mode (the stable - # path — see the SEGFAULT gotcha) reconnects the persisted ~/.telega session in - # ~2s. Then load the main chat list so telega--chats populates. -+# -+# The `(setq telega-use-docker t)` is mandatory and must come BEFORE `(telega t)`: -+# tdlib segfaults in native mode (SEGFAULT gotcha below), and the daemon's default -+# is nil unless something (e.g. an Emacs-config :custom) has already forced it. It -+# was missing here while the Quick Reference and the gotcha both require it — -+# a session that started telega without it on a native-mode daemon would crash the -+# server, surfacing as a triage SCAN FAILED. Match the Quick Reference exactly. - emacsclient -e "(progn -+ (setq telega-use-docker t) - (unless (and (fboundp 'telega-server-live-p) (telega-server-live-p)) (telega t)) - 'started)" - # Poll until Ready with chats synced, or a crash/timeout. Background this with an diff --git a/working/triage-telegram-down-launch/triage-intake.telegram.org.proposed b/working/triage-telegram-down-launch/triage-intake.telegram.org.proposed deleted file mode 100644 index 42d46fe..0000000 --- a/working/triage-telegram-down-launch/triage-intake.telegram.org.proposed +++ /dev/null @@ -1,290 +0,0 @@ -#+TITLE: Triage Intake — Telegram Source -#+AUTHOR: Craig Jennings -#+DATE: 2026-06-09 - -# Source plugin for the triage-intake engine. See triage-intake.org for the -# contract and the Phase A-D orchestration. This file declares ONE source. -# -# General (personal) source: Telegram via the Emacs telega.el package (tdlib -# backend). It lives in .ai/workflows/ and is template-synced, sitting with the -# other general personal sources (personal-gmail, cmail, personal-calendar, -# signal, github-prs) — not the project plugins. Telegram is personal -# messaging, not project-specific. -# -# Unlike signal-cli (a standalone CLI), Telegram has no headless CLI here. The -# client is telega.el running inside Craig's long-lived `emacs --daemon`, so the -# plugin drives it over `emacsclient -e`. tdlib keeps a persisted session in -# ~/.telega (td.binlog), so a started telega reconnects without re-auth. - -* Source: telegram -:PROPERTIES: -:ORDER: 24 -:ENABLED: command -v emacsclient && emacsclient -e "(or (featurep 'telega) (fboundp 'telega))" | grep -q t -:ANCHOR: none -:SUBAGENT_OVER: 40 -:END: - -** Quick reference — full lifecycle - -Telega does not autostart with the Emacs daemon. "Down" is its normal state -unless Craig has Telegram open in Emacs. The scan therefore runs the full -lifecycle every time, never skips because the server is down: - -⚠ *DOWN / not-loaded is the TRIGGER to launch, never a reason to skip or fail.* -This is the exact mistake two projects (work + home, 2026-07-24) made: they -probed telega, saw =(telega-server-live-p)= nil or telega not =featurep=, and -reported =SCAN FAILED: telegram — not loaded= or a silent SKIP — a *blind* -sweep — instead of running Step 1 to start it. A down or unloaded telega is the -normal entry state; =(telega t)= both LOADS the package and STARTS the docker -server (work confirmed: down → =(telega t)= → Ready, 18 chats). So the plugin -MUST run Step 1's launch whenever telega is down/unloaded, wait for Ready, then -scan. =SCAN FAILED= is reserved for a launch that was actually ATTEMPTED and did -not reach Ready (image missing, server crash on start, daemon unreachable) — -never for the pre-launch down state itself. The =:ENABLED:= guard above tests -whether telega is INSTALLED (=fboundp=), not whether the server is up; a down -server never disables the source. - -1. Record prior state: TELEGA_WAS_RUNNING via (telega-server-live-p). -2. Launch (only if not running): - emacsclient -e "(progn (setq telega-use-docker t) (telega t) 'started)" - The setq is mandatory defense: tdlib segfaults outside docker mode - (2026-06-09), and Craig's daemon currently has telega-use-docker nil. - Wait ~2s for Ready, then (telega--loadChats 'main) until telega--chats - is populated. -3. Check messages: the maphash unread scan in ** Scan Step 2 (filters the - messageContactRegistered join-notice noise). -4. Send (needs the server live; /voice personal first — Telegram - occasionally carries WORK communication to Kostya and Vrezh, so treat - sends with the same care as Slack): - emacsclient -e "(telega-chat-send-msg (telega-chat-get <CHAT-ID>) \"<body>\")" -5. Shutdown (ONLY if step 1 recorded not-running): - emacsclient -e "(progn (telega-server-kill) (ignore-errors (telega-kill t)) 'stopped)" - Verify: telega-server-live-p → nil, no zevlg/telega-server container in - docker ps. If Craig had it running, leave it untouched. - -If any lifecycle step fails *after the launch was attempted* (docker image -missing, server crash on start, daemon unreachable, Ready never reached), the -sweep reports it as SCAN FAILED at the top of the summary per the engine's -failure rule — never as a silent skip. This does NOT cover the ordinary -pre-launch down state: a down server means "run Step 1," not "SCAN FAILED." -Craig gets real traffic here, so a blind sweep that skipped the launch is worse -than a clean failure — it hides real unread messages behind a false all-clear. - -** Scan - -Telegram direct messages and groups via telega.el in the running Emacs daemon. -=ANCHOR: none= because telega reports live unread *state* (each chat's -=:unread_count=), not a since-window — the engine substitutes no cutoff. Phase B -uses each message's timestamp only to order and label recency. - -The scan reads the =telega--chats= hash table (chat-id → chat plist), which -telega populates as chats sync. *This is robust to the tdlib server crashing -mid-session* (see the SEGFAULT gotcha below): the hash retains the last-synced -unread counts and =:last_message= even after the server dies, so a scan reading -the hash still returns the most recent known state. - -*** Leave-no-trace lifecycle (start only if needed, shut down only if we started it) - -telega is a long-lived client inside Craig's daemon. If he already has it -running, the scan must leave it running. If it's *not* running, the scan starts -it for the read and shuts it down cleanly afterward, restoring the daemon to its -prior state. The discipline: *record the prior liveness, branch on it at the -end.* - -*** Step 0 — record prior state - -#+begin_src bash -# t if telega's tdlib server was ALREADY live before this scan, nil otherwise. -# Hold this value; Step 3 reads it to decide whether to shut telega down. -TELEGA_WAS_RUNNING=$(emacsclient -e "(and (fboundp 'telega-server-live-p) (telega-server-live-p) t)" 2>/dev/null) -#+end_src - -*** Step 1 — start (docker mode) if not already running, wait for Ready - -#+begin_src bash -# `(telega t)` starts without popping the root buffer. Docker mode (the stable -# path — see the SEGFAULT gotcha) reconnects the persisted ~/.telega session in -# ~2s. Then load the main chat list so telega--chats populates. -# -# The `(setq telega-use-docker t)` is mandatory and must come BEFORE `(telega t)`: -# tdlib segfaults in native mode (SEGFAULT gotcha below), and the daemon's default -# is nil unless something (e.g. an Emacs-config :custom) has already forced it. It -# was missing here while the Quick Reference and the gotcha both require it — -# a session that started telega without it on a native-mode daemon would crash the -# server, surfacing as a triage SCAN FAILED. Match the Quick Reference exactly. -emacsclient -e "(progn - (setq telega-use-docker t) - (unless (and (fboundp 'telega-server-live-p) (telega-server-live-p)) (telega t)) - 'started)" -# Poll until Ready with chats synced, or a crash/timeout. Background this with an -# until-loop so the wait doesn't block; exit on Ready-with-chats OR an abnormal -# server exit. Then force a chat-list load if the hash is thin: -emacsclient -e "(progn (ignore-errors (telega--loadChats 'main)) (ignore-errors (telega--loadChats 'main)) 'loaded)" -#+end_src - -On a persisted session telega reaches status "Ready" within ~2s; the chat list -loads over a few more. If =(hash-table-count telega--chats)= is 0 or thin, -re-issue =telega--loadChats= and poll until it stabilizes. - -*** Step 2 — read unread, classified by last-message type - -The single most important filter: =messageContactRegistered=. Telegram counts a -"<name> joined Telegram" service notice as one unread message, so every contact -from Craig's old address book who ever joined shows as a 1-unread "DM" *that -person never actually sent*. On the 2026-06-09 first scan this was 30 of ~50 -unread chats. Drop them entirely (tally only). - -#+begin_src bash -emacsclient -e "(let (real svc other) - (when (boundp 'telega--chats) - (maphash (lambda (id chat) - (let* ((uc (or (plist-get chat :unread_count) 0)) - (lm (plist-get chat :last_message)) - (ctype (when lm (plist-get (plist-get lm :content) :@type))) - (title (or (ignore-errors (substring-no-properties (telega-chat-title chat))) \"?\"))) - (when (> uc 0) - (cond - ((equal ctype \"messageContactRegistered\") (push title svc)) - ((member ctype '(\"messageText\" \"messagePhoto\" \"messageVideo\" \"messageDocument\" \"messageVoiceNote\" \"messageSticker\" \"messageAnimation\")) - (push (list title uc ctype) real)) - (t (push (list title uc (or ctype \"nil\")) other)))))) - telega--chats)) - (list (cons 'real (nreverse real)) - (cons 'joined-telegram-count (length svc)) - (cons 'other (nreverse other))))" -#+end_src - -For a chat that survives as Action-worthy, pull the last message's text to -classify and summarize: - -#+begin_src bash -# <CHAT-ID> from the maphash key (the scan can also return ids alongside titles) -emacsclient -e "(let ((c (gethash <CHAT-ID> telega--chats))) - (substring-no-properties - (or (telega--tl-get c :last_message :content :text :text) \"\")))" -#+end_src - -*** Step 3 — restore prior state (shut down only if we started it) - -#+begin_src bash -# If telega was NOT running before this scan, shut it down cleanly to leave the -# daemon as we found it. If Craig already had it running, leave it alone. -if [ "$TELEGA_WAS_RUNNING" != "t" ]; then - emacsclient -e "(progn (ignore-errors (telega-server-kill)) (ignore-errors (telega-kill t)) 'killed)" -fi -#+end_src - -⚠ *In docker mode, =telega-kill= alone is not enough.* =telega-kill= buries the -telega buffers but leaves the dockerized tdlib server running (=telega-server-live-p= -stays non-nil). =telega-server-kill= is what actually stops the server. Call -*both* — server-kill then kill — for a clean teardown. Verified clean afterward: -=telega-server-live-p= → nil, root buffer gone, no =zevlg/telega-server= container -left in =docker ps=. Skipping this whole branch when =TELEGA_WAS_RUNNING= is t is -the point of Step 0: never tear down a session Craig is actively using. - -⚠ *SEGFAULT GOTCHA — crashes are spontaneous; treat server death as routine.* -The dockerized =telega-server= (=zevlg/telega-server:latest=, image built -2026-06-04, tdlib 1.8.64) SIGSEGVs (exit 139) *on its own*, minutes-to-hours -into a session — 11 host coredumps between 2026-06-09 and 2026-06-11, several at -times when no triage verb was running. The 2026-06-11 investigation reproduced -the crash-free verbs and the spontaneous deaths side by side: coredump -backtraces show a corrupted stack (memory corruption in the musl build), and -no newer image exists upstream. Earlier theories — "native mode is the trigger", -"toggle-read is the trigger" — were timing coincidences; the verbs are sound. - -Operationally: docker mode stays mandatory (=telega-use-docker= = t; the setq -before =(telega t)= is still the right defense), and *every action batch checks -the server first* — =(process-live-p (telega-server--proc))= — restarting via -=(telega t)= when dead and re-checking Ready before firing verbs. A mid-sweep -death is recoverable, not an abort: restart, confirm Ready, resume. Durable-fix -candidates if the crashing gets worse: pin a pre-2026-06 image digest, build -=telega-server= natively against tdlib, or report upstream to zevlg with the -coredumps (=coredumpctl list /usr/bin/telega-server=). - -Defense in depth: even if the server does die, the scan still works because it -reads the cached =telega--chats= hash, not a live query. A dead server is -*scan-only* — you can still report unread state, but cannot read new bodies, mark -read, or reply until it restarts. Treat that as "scan-only, no actions this run" -and say so. - -** Classify - -Bias: Craig's personal Telegram is *spam-dominated* with a thin layer of real -signal. The opposite of Signal (high signal/low volume) — here the volume is -high and almost all noise. Filter aggressively; surface only the few real -threads. Kostya and Vrezh occasionally reach Craig here, so a real DM from a -work contact is Action, full stop. - -- *Noise-trash (tally only, never itemized):* - - =messageContactRegistered= "joined Telegram" notices — always noise, no - matter whose name is on them. The real contacts Craig knows live here; a - join notice is not a message from them. - - Romance/crypto spam DMs — the signature is an emoji-laden handle or a - two-word "RealName + FantasyWord" suffix (=Gayle ⚾🤎RoyalVineyard=, - =Cherie🌷🏰 InfiniteRhapsody=, =Jane 🍒🔥=, =Luna Skye=). One unread, - unsolicited, no prior thread. - - =Deleted Account-NNNN= threads, blank-title chats, bot channels - (=Z-Library Official=), Telegram's own =✔️Telegram= service notices. -- *Noise-keep (never reported):* unread in dev-community groups Craig follows — - =GNU Emacs=, =zed=, =Kitty=, and similar. Skipped in sweep reports entirely — - not even a name + count line — unless Craig specifically asks about them - (Craig's ruling, 2026-06-11, via the work project's handoff). Leave them - unread; they're reading material, not signal. -- *Action:* a real text/voice/media message from a *known personal contact* in - an existing one-to-one thread — an explicit ask, a question, a reply owed. On - a spam-heavy account these are rare; when one appears, surface it prominently - with the sender + gist, because it's the needle in the haystack. - -The 2026-06-09 calibration run: 30 join-notices + ~10 spam/deleted/bot + 3 dev -groups + 0 real personal DMs. Expect most sweeps to look like this — a clean -"nothing real" is the common, correct result. - -** Render - -#+begin_example -**Telegram — N unread chats (M real after filtering).** <one-line summary> -- Action: <real DMs from known contacts, sender + gist, reply owed called out> -- Noise: K joined-Telegram notices, J spam/bot/deleted (tally only) -#+end_example - -Dev-community group traffic never appears here — no FYI line, no name + count — -unless Craig asks for it in that sweep (2026-06-11 ruling). Real DMs from known -contacts still surface as Action. - -Omit the block entirely when there's nothing but group traffic, join-notices, -and spam — under the engine's deltas-only rule that's a no-change source. Render -the block only when there's an Action item or a Noise tally worth a state-change -suggestion (e.g. a trash batch). - -** Actions - -Actions need the tdlib server *live* (see the SEGFAULT gotcha — a dead server is -scan-only). All run through telega in the daemon: - -- reply :: =emacsclient -e "(telega-chat-send-msg (telega-chat-get <CHAT-ID>) \"<body>\")"= — public-facing (goes out under Craig's name), so run =/voice personal= before sending. Prefer a body file for multi-line. -- mark-read :: verified 2026-06-11 (the previously documented =telega-chat--mark-read= never existed in telega). The idempotent per-chat verb: - - #+begin_example - emacsclient -e "(let ((chat (telega-chat-get <CHAT-ID>))) - (telega--viewMessages chat (list (plist-get chat :last_message)) - :source '(:@type \"messageSourceChatList\") :force t) - (telega--readAllChatMentions chat) - (telega--readAllChatReactions chat))" - #+end_example - - =telega-chat-toggle-read= also works but *toggles*: on a chat with zero unread it marks the chat UNREAD, so scripting must guard on =(> (plist-get chat :unread_count) 0)=. Never mark the whole account read blindly; a real DM is handled deliberately, not swept. -- delete-join-notice :: standing policy (Craig, 2026-06-11): a chat whose *newest* message is a =messageContactRegistered= "joined Telegram" notice is a chat Craig never responded to and doesn't want to keep — *delete it* rather than mark it read. The bulk sweep (returns the count deleted): - - #+begin_example - emacsclient -e "(let ((n 0)) - (maphash (lambda (_id chat) - (when (equal (plist-get (plist-get (plist-get chat :last_message) :content) :@type) - \"messageContactRegistered\") - (telega--deleteChatHistory chat t nil) - (setq n (1+ n)))) - telega--chats) - n)" - #+end_example - - =telega--deleteChatHistory chat t nil= removes the chat from the list on Craig's side only (no revoke). First run 2026-06-11 deleted 41 such chats and cut the unread-chat count from 48 to 16. -- open :: =emacsclient -e "(telega-chat-with (telega-chat-get <CHAT-ID>))"= — pop the chat buffer for Craig to read/handle by hand (useful when a real DM needs a considered reply). diff --git a/working/triage-telegram-down-launch/triage-intake.telegram.org.superseded-1723 b/working/triage-telegram-down-launch/triage-intake.telegram.org.superseded-1723 deleted file mode 100644 index 497f74b..0000000 --- a/working/triage-telegram-down-launch/triage-intake.telegram.org.superseded-1723 +++ /dev/null @@ -1,273 +0,0 @@ -#+TITLE: Triage Intake — Telegram Source -#+AUTHOR: Craig Jennings -#+DATE: 2026-06-09 - -# Source plugin for the triage-intake engine. See triage-intake.org for the -# contract and the Phase A-D orchestration. This file declares ONE source. -# -# General (personal) source: Telegram via the Emacs telega.el package (tdlib -# backend). It lives in .ai/workflows/ and is template-synced, sitting with the -# other general personal sources (personal-gmail, cmail, personal-calendar, -# signal, github-prs) — not the project plugins. Telegram is personal -# messaging, not project-specific. -# -# Unlike signal-cli (a standalone CLI), Telegram has no headless CLI here. The -# client is telega.el running inside Craig's long-lived `emacs --daemon`, so the -# plugin drives it over `emacsclient -e`. tdlib keeps a persisted session in -# ~/.telega (td.binlog), so a started telega reconnects without re-auth. - -* Source: telegram -:PROPERTIES: -:ORDER: 24 -:ENABLED: command -v emacsclient && emacsclient -e "(or (featurep 'telega) (fboundp 'telega))" | grep -q t -:ANCHOR: none -:SUBAGENT_OVER: 40 -:END: - -** Quick reference — full lifecycle - -Telega does not autostart with the Emacs daemon. "Down" is its normal state -unless Craig has Telegram open in Emacs. The scan therefore runs the full -lifecycle every time, never skips because the server is down: - -1. Record prior state: TELEGA_WAS_RUNNING via (telega-server-live-p). -2. Launch (only if not running): - emacsclient -e "(progn (setq telega-use-docker t) (telega t) 'started)" - The setq is mandatory defense: tdlib segfaults outside docker mode - (2026-06-09), and Craig's daemon currently has telega-use-docker nil. - Wait ~2s for Ready, then (telega--loadChats 'main) until telega--chats - is populated. -3. Check messages: the maphash unread scan in ** Scan Step 2 (filters the - messageContactRegistered join-notice noise). -4. Send (needs the server live; /voice personal first — Telegram - occasionally carries WORK communication to Kostya and Vrezh, so treat - sends with the same care as Slack): - emacsclient -e "(telega-chat-send-msg (telega-chat-get <CHAT-ID>) \"<body>\")" -5. Shutdown (ONLY if step 1 recorded not-running): - emacsclient -e "(progn (telega-server-kill) (ignore-errors (telega-kill t)) 'stopped)" - Verify: telega-server-live-p → nil, no zevlg/telega-server container in - docker ps. If Craig had it running, leave it untouched. - -If any lifecycle step fails (docker image missing, server crash, daemon -unreachable), the sweep reports it as SCAN FAILED at the top of the summary -per the engine's failure rule — never as a silent skip. Craig gets real -traffic here. - -** Scan - -Telegram direct messages and groups via telega.el in the running Emacs daemon. -=ANCHOR: none= because telega reports live unread *state* (each chat's -=:unread_count=), not a since-window — the engine substitutes no cutoff. Phase B -uses each message's timestamp only to order and label recency. - -The scan reads the =telega--chats= hash table (chat-id → chat plist), which -telega populates as chats sync. *This is robust to the tdlib server crashing -mid-session* (see the SEGFAULT gotcha below): the hash retains the last-synced -unread counts and =:last_message= even after the server dies, so a scan reading -the hash still returns the most recent known state. - -*** Leave-no-trace lifecycle (start only if needed, shut down only if we started it) - -telega is a long-lived client inside Craig's daemon. If he already has it -running, the scan must leave it running. If it's *not* running, the scan starts -it for the read and shuts it down cleanly afterward, restoring the daemon to its -prior state. The discipline: *record the prior liveness, branch on it at the -end.* - -*** Step 0 — record prior state - -#+begin_src bash -# t if telega's tdlib server was ALREADY live before this scan, nil otherwise. -# Hold this value; Step 3 reads it to decide whether to shut telega down. -TELEGA_WAS_RUNNING=$(emacsclient -e "(and (fboundp 'telega-server-live-p) (telega-server-live-p) t)" 2>/dev/null) -#+end_src - -*** Step 1 — start (docker mode) if not already running, wait for Ready - -#+begin_src bash -# `(telega t)` starts without popping the root buffer. Docker mode (the stable -# path — see the SEGFAULT gotcha) reconnects the persisted ~/.telega session in -# ~2s. Then load the main chat list so telega--chats populates. -# -# The `(setq telega-use-docker t)` is mandatory and must come BEFORE `(telega t)`: -# tdlib segfaults in native mode (SEGFAULT gotcha below), and the daemon's default -# is nil unless something (e.g. an Emacs-config :custom) has already forced it. It -# was missing here while the Quick Reference and the gotcha both require it — -# a session that started telega without it on a native-mode daemon would crash the -# server, surfacing as a triage SCAN FAILED. Match the Quick Reference exactly. -emacsclient -e "(progn - (setq telega-use-docker t) - (unless (and (fboundp 'telega-server-live-p) (telega-server-live-p)) (telega t)) - 'started)" -# Poll until Ready with chats synced, or a crash/timeout. Background this with an -# until-loop so the wait doesn't block; exit on Ready-with-chats OR an abnormal -# server exit. Then force a chat-list load if the hash is thin: -emacsclient -e "(progn (ignore-errors (telega--loadChats 'main)) (ignore-errors (telega--loadChats 'main)) 'loaded)" -#+end_src - -On a persisted session telega reaches status "Ready" within ~2s; the chat list -loads over a few more. If =(hash-table-count telega--chats)= is 0 or thin, -re-issue =telega--loadChats= and poll until it stabilizes. - -*** Step 2 — read unread, classified by last-message type - -The single most important filter: =messageContactRegistered=. Telegram counts a -"<name> joined Telegram" service notice as one unread message, so every contact -from Craig's old address book who ever joined shows as a 1-unread "DM" *that -person never actually sent*. On the 2026-06-09 first scan this was 30 of ~50 -unread chats. Drop them entirely (tally only). - -#+begin_src bash -emacsclient -e "(let (real svc other) - (when (boundp 'telega--chats) - (maphash (lambda (id chat) - (let* ((uc (or (plist-get chat :unread_count) 0)) - (lm (plist-get chat :last_message)) - (ctype (when lm (plist-get (plist-get lm :content) :@type))) - (title (or (ignore-errors (substring-no-properties (telega-chat-title chat))) \"?\"))) - (when (> uc 0) - (cond - ((equal ctype \"messageContactRegistered\") (push title svc)) - ((member ctype '(\"messageText\" \"messagePhoto\" \"messageVideo\" \"messageDocument\" \"messageVoiceNote\" \"messageSticker\" \"messageAnimation\")) - (push (list title uc ctype) real)) - (t (push (list title uc (or ctype \"nil\")) other)))))) - telega--chats)) - (list (cons 'real (nreverse real)) - (cons 'joined-telegram-count (length svc)) - (cons 'other (nreverse other))))" -#+end_src - -For a chat that survives as Action-worthy, pull the last message's text to -classify and summarize: - -#+begin_src bash -# <CHAT-ID> from the maphash key (the scan can also return ids alongside titles) -emacsclient -e "(let ((c (gethash <CHAT-ID> telega--chats))) - (substring-no-properties - (or (telega--tl-get c :last_message :content :text :text) \"\")))" -#+end_src - -*** Step 3 — restore prior state (shut down only if we started it) - -#+begin_src bash -# If telega was NOT running before this scan, shut it down cleanly to leave the -# daemon as we found it. If Craig already had it running, leave it alone. -if [ "$TELEGA_WAS_RUNNING" != "t" ]; then - emacsclient -e "(progn (ignore-errors (telega-server-kill)) (ignore-errors (telega-kill t)) 'killed)" -fi -#+end_src - -⚠ *In docker mode, =telega-kill= alone is not enough.* =telega-kill= buries the -telega buffers but leaves the dockerized tdlib server running (=telega-server-live-p= -stays non-nil). =telega-server-kill= is what actually stops the server. Call -*both* — server-kill then kill — for a clean teardown. Verified clean afterward: -=telega-server-live-p= → nil, root buffer gone, no =zevlg/telega-server= container -left in =docker ps=. Skipping this whole branch when =TELEGA_WAS_RUNNING= is t is -the point of Step 0: never tear down a session Craig is actively using. - -⚠ *SEGFAULT GOTCHA — crashes are spontaneous; treat server death as routine.* -The dockerized =telega-server= (=zevlg/telega-server:latest=, image built -2026-06-04, tdlib 1.8.64) SIGSEGVs (exit 139) *on its own*, minutes-to-hours -into a session — 11 host coredumps between 2026-06-09 and 2026-06-11, several at -times when no triage verb was running. The 2026-06-11 investigation reproduced -the crash-free verbs and the spontaneous deaths side by side: coredump -backtraces show a corrupted stack (memory corruption in the musl build), and -no newer image exists upstream. Earlier theories — "native mode is the trigger", -"toggle-read is the trigger" — were timing coincidences; the verbs are sound. - -Operationally: docker mode stays mandatory (=telega-use-docker= = t; the setq -before =(telega t)= is still the right defense), and *every action batch checks -the server first* — =(process-live-p (telega-server--proc))= — restarting via -=(telega t)= when dead and re-checking Ready before firing verbs. A mid-sweep -death is recoverable, not an abort: restart, confirm Ready, resume. Durable-fix -candidates if the crashing gets worse: pin a pre-2026-06 image digest, build -=telega-server= natively against tdlib, or report upstream to zevlg with the -coredumps (=coredumpctl list /usr/bin/telega-server=). - -Defense in depth: even if the server does die, the scan still works because it -reads the cached =telega--chats= hash, not a live query. A dead server is -*scan-only* — you can still report unread state, but cannot read new bodies, mark -read, or reply until it restarts. Treat that as "scan-only, no actions this run" -and say so. - -** Classify - -Bias: Craig's personal Telegram is *spam-dominated* with a thin layer of real -signal. The opposite of Signal (high signal/low volume) — here the volume is -high and almost all noise. Filter aggressively; surface only the few real -threads. Kostya and Vrezh occasionally reach Craig here, so a real DM from a -work contact is Action, full stop. - -- *Noise-trash (tally only, never itemized):* - - =messageContactRegistered= "joined Telegram" notices — always noise, no - matter whose name is on them. The real contacts Craig knows live here; a - join notice is not a message from them. - - Romance/crypto spam DMs — the signature is an emoji-laden handle or a - two-word "RealName + FantasyWord" suffix (=Gayle ⚾🤎RoyalVineyard=, - =Cherie🌷🏰 InfiniteRhapsody=, =Jane 🍒🔥=, =Luna Skye=). One unread, - unsolicited, no prior thread. - - =Deleted Account-NNNN= threads, blank-title chats, bot channels - (=Z-Library Official=), Telegram's own =✔️Telegram= service notices. -- *Noise-keep (never reported):* unread in dev-community groups Craig follows — - =GNU Emacs=, =zed=, =Kitty=, and similar. Skipped in sweep reports entirely — - not even a name + count line — unless Craig specifically asks about them - (Craig's ruling, 2026-06-11, via the work project's handoff). Leave them - unread; they're reading material, not signal. -- *Action:* a real text/voice/media message from a *known personal contact* in - an existing one-to-one thread — an explicit ask, a question, a reply owed. On - a spam-heavy account these are rare; when one appears, surface it prominently - with the sender + gist, because it's the needle in the haystack. - -The 2026-06-09 calibration run: 30 join-notices + ~10 spam/deleted/bot + 3 dev -groups + 0 real personal DMs. Expect most sweeps to look like this — a clean -"nothing real" is the common, correct result. - -** Render - -#+begin_example -**Telegram — N unread chats (M real after filtering).** <one-line summary> -- Action: <real DMs from known contacts, sender + gist, reply owed called out> -- Noise: K joined-Telegram notices, J spam/bot/deleted (tally only) -#+end_example - -Dev-community group traffic never appears here — no FYI line, no name + count — -unless Craig asks for it in that sweep (2026-06-11 ruling). Real DMs from known -contacts still surface as Action. - -Omit the block entirely when there's nothing but group traffic, join-notices, -and spam — under the engine's deltas-only rule that's a no-change source. Render -the block only when there's an Action item or a Noise tally worth a state-change -suggestion (e.g. a trash batch). - -** Actions - -Actions need the tdlib server *live* (see the SEGFAULT gotcha — a dead server is -scan-only). All run through telega in the daemon: - -- reply :: =emacsclient -e "(telega-chat-send-msg (telega-chat-get <CHAT-ID>) \"<body>\")"= — public-facing (goes out under Craig's name), so run =/voice personal= before sending. Prefer a body file for multi-line. -- mark-read :: verified 2026-06-11 (the previously documented =telega-chat--mark-read= never existed in telega). The idempotent per-chat verb: - - #+begin_example - emacsclient -e "(let ((chat (telega-chat-get <CHAT-ID>))) - (telega--viewMessages chat (list (plist-get chat :last_message)) - :source '(:@type \"messageSourceChatList\") :force t) - (telega--readAllChatMentions chat) - (telega--readAllChatReactions chat))" - #+end_example - - =telega-chat-toggle-read= also works but *toggles*: on a chat with zero unread it marks the chat UNREAD, so scripting must guard on =(> (plist-get chat :unread_count) 0)=. Never mark the whole account read blindly; a real DM is handled deliberately, not swept. -- delete-join-notice :: standing policy (Craig, 2026-06-11): a chat whose *newest* message is a =messageContactRegistered= "joined Telegram" notice is a chat Craig never responded to and doesn't want to keep — *delete it* rather than mark it read. The bulk sweep (returns the count deleted): - - #+begin_example - emacsclient -e "(let ((n 0)) - (maphash (lambda (_id chat) - (when (equal (plist-get (plist-get (plist-get chat :last_message) :content) :@type) - \"messageContactRegistered\") - (telega--deleteChatHistory chat t nil) - (setq n (1+ n)))) - telega--chats) - n)" - #+end_example - - =telega--deleteChatHistory chat t nil= removes the chat from the list on Craig's side only (no revoke). First run 2026-06-11 deleted 41 such chats and cut the unread-chat count from 48 to 16. -- open :: =emacsclient -e "(telega-chat-with (telega-chat-get <CHAT-ID>))"= — pop the chat buffer for Craig to read/handle by hand (useful when a real DM needs a considered reply). |