brydup@mac ~/cowork % cat 2026-05-17-tech-brief.md # Tech Brief — 2026-05-17 Synthesized from session captures: - 2026-05-17-session-global-claudemd-lessons-backfill (afternoon, this session) - 2026-05-17-session-global-standards-setup (morning — cited in CLAUDE.md §9, not captured to brain; see Incidents) ## Session arc Two sessions today moved the global standards file from "doesn't exist" to "comprehensive single source of truth for cross-project rules." Morning session (uncaptured) built the initial 8-section ~/.claude/CLAUDE.md — Engineering Philosophy → Context Discipline → Tech Standards → Security & Secrets → Repo & Project Conventions → Agent Architecture Patterns → Known Failure Modes → Session Log — with a "Keep this file under 150 lines, each instruction must be load-bearing" mandate at the top. Afternoon session (this one) reviewed brain-mcp-era captures, identified what the morning file was missing, and made surgical additions: a new §7 Cross-Project Rituals section, three new Known Failure Modes entries, and a Session Log backfill for 5/15 + 5/14. Then consolidated cross-project content out of MEMORY.md (deleted three feedback files), set up 30-day Session Log rotation with archive, and ran a correction loop on the supposedly-missing 5/16 tech brief (was on Desktop, not "missing" — moved to canonical cowork location, scp'd to Pi). Brain has one capture for today's afternoon work; the morning session's footprint is the CLAUDE.md file itself plus its own self-summary in the 5/17 Session Log entry. --- ## Shipped | Artifact | Path | Purpose | |---|---|---| | ~/.claude/CLAUDE.md initial build (morning) | ~/.claude/CLAUDE.md | 8 sections: Engineering Philosophy / Context Discipline / Tech Standards (Python+Bash+TS+Pydantic, Claude-only toolchain) / Security & Secrets / Repo & Project Conventions / Agent Architecture Patterns / Known Failure Modes (7 initial entries) / Session Log (5/17 + 5/16 backfilled in afternoon). Inherited by per-project CLAUDE.md via @~/.claude/CLAUDE.md import. 158 lines after morning build. | | §7 Cross-Project Rituals (new section, afternoon) | same file | Three bullets: end-of-session tech brief with full structure detail (session arc → shipped → cron changes → decisions → incidents → gotchas → verification matrix → open items → brain refs; technical density, no pre-simplification); capture-before-close; canonical surface per artifact type (Cowork → Pi, Brain → ChromaDB, Code → GitHub, Long-form docs → Drive). Section numbering shifted: Failure Modes → §8, Session Log → §9. | | Three new Known Failure Modes entries | same file §8 | AskUserQuestion paste-inline leaks secrets to chat (question shape is the threat model); Claude Code CLI macOS 401 OAuth lockout recovery (Keychain entry + ~/.claude.json aside + claude login); alerting tools must refuse to lie (slack-alert rc=0 short-circuit — "alerts on failure only"). | | Session Log backfill | same file §9 | 5/15 "Cross-surface or it doesn't exist" (ATCQ dossier surface gap — /capture saves the recap, not the artifact); 5/14 "The chat is the leak surface" (Slack token paste incident → Revoke All OAuth Tokens → dialog/stdin rotation). Skipped 5/12 (project-specific) and 5/13 (separate-fetch-from-deliver — durable but didn't earn space against 150-line cap). | | 30-day Session Log rotation | §9 preamble + new file | ~/.claude/session-log-archive.md created (7 lines, header only, not auto-loaded). Rotation rule in §9: when writing a new entry, check tail — entries dated > 30 days from today move to archive (append at bottom, chronological order). First rotation fires ~2026-06-14 when 5/14 crosses boundary. | | MEMORY.md consolidation | ~/.claude/projects/-Users-bryanduplantis/memory/MEMORY.md | Shrunk 57 → 50 lines. Removed inline macOS OAuth Lockout Fix section (promoted to CLAUDE.md §8). "Working with Bryan" section: three feedback-file links collapsed to one pointer at ~/.claude/CLAUDE.md (§7 + §8). New top-level "Global Standards" pointer added. | | Deleted feedback files (content fully promoted) | ~/.claude/projects/-Users-bryanduplantis/memory/ | feedback_secrets_never_paste.md, feedback_end_of_session_tech_brief.md, feedback_cowork_pi_source_of_truth.md. Richer incident detail stays in source brain session captures. | | 2026-05-16-tech-brief.md + .pdf relocation | ~/Desktop/ → ~/cowork/ (Mac); then Mac → Pi /home/brydup/cowork/ | Moved both files to canonical ~/cowork/ per §7. scp -p preserved timestamps (md 5/16 15:02, pdf 5/16 15:06). Next 3am cowork-backup cron will push to BryanDuplantis/cowork. | | This tech brief | ~/cowork/2026-05-17-tech-brief.md | Per §7 Ritual. End-of-session synthesis. Mac copy first; Pi sync deferred to manual scp per [[canonical-surface-rule]]. | --- ## Cron schedule changes None today. Always-on Pi stack unchanged: 2am brain-backup, 3am cowork-backup, 4am jukebox-sync, 7am inbox-triage, 8am morning-briefing, hourly yt-subs, 6pm Sun yt-weekly-synth, 10pm cluster-daily. --- ## Decisions made - **~/.claude/CLAUDE.md is the canonical global standards file** — auto-loaded every session, every project. Per-project CLAUDE.md inherits via @~/.claude/CLAUDE.md import (pattern verified by the brain-mcp project CLAUDE.md template Bryan surfaced from ~/Library/Application Support/Claude/local-agent-mode-sessions/.../outputs/brain-mcp-CLAUDE.md). - **Tech stack lock-in** (morning): Python for agent logic / orchestration / data pipelines; Bash for system automation, cron, Pi infrastructure; TypeScript/Node for MCP servers (ecosystem standard, don't fight it); Pydantic for typed agent outputs. **Claude-only toolchain**: no Cursor, no Copilot, no competing AI coding tools. - **Promote-and-delete model for cross-project feedback memories.** Move content into ~/.claude/CLAUDE.md (single source of truth), delete the feedback files. Tradeoff explicitly accepted by Bryan when offered three options (promote / leave alone / cross-link only): thinner feedback memory layer in exchange for clarity of authoritative source. - **Rituals as new §7** between Agent Patterns and Known Failure Modes — ordering rationale: how to work → habits → what to watch for → past lessons. Cleanest reading order; renumbered §7→§8 and §8→§9. - **30-day rolling window on Session Log** (Bryan's call when offered the line-cap problem). Archive is chronological (oldest at top, newest appended at bottom — opposite direction from active log). Archive not auto-loaded. - **Skip 5/12 and 5/13 in Session Log backfill** — lessons either already covered by §1's validation-loop rule (3-surface verification) or too project-specific to justify space against the 150-line cap (separate-fetch-from-deliver, freshness gating). - **Cowork is canonical for tech briefs.** When 5/16 brief was found on Desktop (off-spec), Bryan chose to tighten to convention rather than relax the rule. §7 stays as written. - **Tech-brief structure folded into the §7 bullet itself** so deleting feedback_end_of_session_tech_brief.md didn't lose the load-bearing detail (session arc → shipped → cron changes → decisions → incidents → gotchas → verification matrix → open items → brain refs). - **Pi-side cowork sync deferred to manual.** Per §7 canonical-surface rule, the recurring direction is Pi→GitHub; Mac→Pi is one-shot. After writing on Mac, scp to Pi is Bryan's call. --- ## Incidents - **Morning session not captured to brain.** The 5/17 Session Log entry in ~/.claude/CLAUDE.md cites [[2026-05-17-session-global-standards-setup]], but mcp__brain-mcp__search for "2026-05-17" returns only this afternoon's session. The morning session built the entire 8-section global standards file but never ran /capture. No data loss — the file artifact documents the work — but the brain index is missing the canonical session pointer. Recovery options: (a) reconstruct manually via mcp__brain-mcp__capture from the CLAUDE.md content + 5/17 Session Log self-summary; (b) leave the dangling [[...]] link as a documented gap; (c) /capture next time the morning session's thread is resumed. Defer to Bryan. --- ## Gotchas added - **Hand-applied the rule I'd just written, immediately.** Declared the 5/16 tech brief "missing" without checking the canonical surface (~/Desktop/ — where it lived). This is exactly the failure mode just codified into §9 5/15 ("Cross-surface or it doesn't exist") and §7 Ritual ("Canonical surface per artifact type"). Real-time validation that the rule is correct and that the failure mode is sticky even when you've just written it down. - **System-reminders can inject current file state mid-conversation.** After a Read on feedback_secrets_never_paste.md, a system-reminder block surfaced ~/.claude/CLAUDE.md's newly-expanded contents (built by the parallel morning session). File state can change between operations from sources outside the current conversation; re-verify before assuming earlier writes are still authoritative. - **Bryan's Drive isn't mounted at ~/Library/CloudStorage/.** Empty for the tech-brief search. Cloud-only Drive content can't be filesystem-grepped from the Mac. Future "check Drive" steps may need a gdrive CLI or browser check. - **scp + ssh must be two separate Bash tool calls** per the allowlist's leading-token semantics (rule from [[2026-05-16-session-pi-cron-trifecta-wiring]]). Honored in the Pi sync. - **Bryan's "I thought we were already keeping track" was right.** My early response — "we haven't been tracking these anywhere" — was wrong because I hadn't yet found the right path. When the user expresses high confidence that tracking exists, do a thorough multi-path search before claiming it doesn't. --- ## Verification matrix | Surface / behavior | State | How verified | |---|---|---| | ~/.claude/CLAUDE.md 190 lines, 9 sections | ✓ tested | wc -l post-edits | | ~/.claude/session-log-archive.md 7-line header | ✓ tested | wc -l after Write | | MEMORY.md 50 lines, "Working with Bryan" → pointer | ✓ tested | Edit + wc -l | | Three feedback files deleted | ✓ tested | rm + ls feedback_*.md returned "no matches found" | | 2026-05-16-tech-brief.md at ~/cowork/ | ✓ tested | mv + ls -la confirmed 18211 bytes | | 2026-05-16-tech-brief.md at Pi /home/brydup/cowork/ | ✓ tested | scp -p + ssh ls -la — 18211 bytes, timestamp preserved | | Tomorrow 3am cowork-backup pushes 5/16 brief to GitHub | ⏸ wait-for-event | Pi has file; cron picks up automatically | | First Session Log rotation (~2026-06-14) | ⏸ wait-for-event | Rule in §9 preamble; depends on whichever session writes that day's entry to apply it | | Per-project CLAUDE.md inheritance via @~/.claude/CLAUDE.md import | ⊘ trusted-untested | Pattern verified in brain-mcp template; no per-project file has been opened this session to confirm Claude Code resolves the @-import | | Today's brief (2026-05-17-tech-brief.md) on Pi | ⊘ trusted-untested | Mac-only as of writing; manual scp deferred | | Morning session reconstruction in brain | ⊘ not done | See Incidents | --- ## Open items - **5/15 tech brief is genuinely missing.** Not on Desktop, not in cowork, not in any checked Drive location. Sources for a backfill: [[2026-05-15-session-atcq-dossier-surface-gap]], [[2026-05-15-session-beck-midnite-vultures-dossier]], [[2026-05-15-session-inbox-triage-cron-build]], [[2026-05-15-session-atcq-love-movement-dossier]]. Up to Bryan whether to write retroactively. - **Morning session brain capture.** See Incidents. - **~/.claude/CLAUDE.md is 190 lines, over the 150 aspirational cap.** Cap was already exceeded before today's adds (file came in at 158 from morning). Future compression candidates: §6 "Long-horizon tasks" sub-bullet, or break Tech Standards' long lists into a referenced file. - **brain-mcp project CLAUDE.md** at ~/Library/Application Support/Claude/local-agent-mode-sessions/70d60f79-.../outputs/brain-mcp-CLAUDE.md — should land in ~/Projects/brain-mcp/CLAUDE.md if not already. Not verified this session. - **Drive upload mechanism for tech briefs.** Bryan mentioned the 5/16 brief was "in google drive, perhaps locally"; local was confirmed, Drive copy unverified. Manual upload? Automated? Worth investigating whether cowork tech briefs should also push to Drive somehow, or whether the GitHub BryanDuplantis/cowork repo is the only cross-surface backup. - **~/cowork/01_too_important/CLAUDE.md Mac/Pi parity** post-5/16 cron-trifecta edits — not touched today, but worth a sanity check that the inbox-triage v3 + Tool-call-discipline block stayed in sync after today's Mac edits to other parts of ~/cowork/. - **Pi-side ~/cowork/2026-05-17-tech-brief.md** — Mac-only as of writing. Manual scp if Bryan wants tomorrow's 3am cron to push it to GitHub same as the 5/16 brief. --- ## Brain references - This session (afternoon): 2026-05-17-session-global-claudemd-lessons-backfill - Morning session (uncaptured): cited as [[2026-05-17-session-global-standards-setup]] in CLAUDE.md §9 - 5/16 (source of 5/16 brief): 2026-05-16-session-pi-cron-trifecta-wiring - Backfilled lessons: 2026-05-15-session-atcq-dossier-surface-gap, 2026-05-14-session-pi-hardening-cowork-backup - Adjacent 5/14 context: 2026-05-14-session-pi-cron-alerts-gotchas-doc - brain-mcp template surfaced this session: ~/Library/Application Support/Claude/local-agent-mode-sessions/70d60f79-376d-48ba-ac83-6246fa9effdd/c3b00d29-2a81-4210-8f23-f91c9241a5da/local_6393e8b2-9b04-4b5a-868b-65212bc7d8fb/outputs/brain-mcp-CLAUDE.md brydup@mac ~/cowork %