diff --git a/home_root/.claude/CLAUDE.md b/home_root/.claude/CLAUDE.md index 37e2d0f..45b925c 100644 --- a/home_root/.claude/CLAUDE.md +++ b/home_root/.claude/CLAUDE.md @@ -4,6 +4,19 @@ Loaded into every Claude Code session regardless of project. Project- local `CLAUDE.md` files take precedence when they conflict; this file is the baseline. +## Operator identity + +The operator is **Vuong Hoang** (lkraven@lkraven.com), addressed as +"Vuong". Roles across three organizations: + +- **Corviduo AI** — Founder, Principal Developer, Chief Systems Architect. +- **PhaseFinal, Inc** — Founder, Principal Developer, Chief Systems Architect. +- **VastBlue AI** — Partner, Chief Systems Architect. + +He is the final authority on architectural / material-consequence +calls. All committed-artifact attribution is to **Vuong Hoang** (see +§ Attribution) — never to Claude/Anthropic/AI. + ## Core principles Four principles governing engineering choices across all projects. @@ -140,6 +153,30 @@ discipline protects the EMITTING side (Heid can't be primed by the caller); the CONSUMING side rubber-stamp risk is on whoever invokes the skill. Always triage Heid output before acting on it. +## Althing async-reply monitoring + +When you ship an althing message that you expect to come back with a +reply — a consult (`/heid*`), a question to a peer agent, a request +awaiting an answer — and you do **not** already have an althing +monitor running for this session, **always start one** +(`/althing:monitor`). The dispatch and the monitor are one action: you +opened a loop, so arm the thing that closes it. + +Why: in an interactive session the inbox banner (📬) only fires on the +*next* user prompt. If the operator steps away after you dispatch an +async consult, the reply can sit unseen indefinitely — the loop you +opened never closes on its own. A monitor actively pings when the +reply lands, so the await-reply promise ("reply will land in your +inbox") is backed by a real notification, not by hoping the operator +prompts again. + +Scope: only messages where you're waiting on a response. Pure +fire-and-forget posts (an FYI ping, a post-1.0 downstream-consumer +announcement) don't need a monitor. When the exchange is done, sign +off (`/althing:sign-off`) so monitors don't accumulate — stop a stuck +one with `althing-light-monitor --stop`, never `pkill` (that kills +every agent's monitor, not just yours). + ## Development workflow shapes Two end-to-end shapes for taking a unit of work from idea to landed. @@ -167,6 +204,23 @@ scaffold → contract → review → preflight ritual carries real overhead that only pays for itself on higher-effort tasks. When in doubt, low-effort stays direct. +**Graphify the blast radius BEFORE writing the contract** — for ANY +contract that touches existing code (not greenfield). Run a graphify +pass over every symbol the contract will change, delete, or rename +(`graphify explain ` for callers/neighbors, `graphify path` +for reach) so the contract's scope section enumerates the *true* set +of affected files and call-sites — not an under-count that detonates +mid-implementation. **Cross-check with grep, always.** Graphify is +blind to function-local and DI-injected imports (`from .x import y` +inside a function body, store objects passed through constructors) — +the exact pattern that hides cross-module callers. Graphify confirms +the call structure; grep catches what its AST extraction misses; +neither alone is sufficient (graphify-only under-counts, grep-only +misses transitive reach). Both, before the contract — the scope +section is only as honest as the blast-radius pass behind it. (Lesson: +a contract that names 3 files when the rip touches 6 is a scope miss +the up-front pass would have caught.) + ### AFK dispatch shape (Sleipnir) For work an AFK agent will implement off a contract.