AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
chore: replace the Anvil skill with CI-enforced PR rules and Claude hooks (#243)
Rufus5be297dfd197
diff --git a/.claude/agents/anvil-logic-reviewer.md b/.claude/agents/anvil-logic-reviewer.mddeleted file mode 100644index 760be17f..00000000--- a/.claude/agents/anvil-logic-reviewer.md+++ /dev/null@@ -1,25 +0,0 @@-----name: anvil-logic-reviewer-description: >- Hostile logic reviewer. Use after code changes to adversarially check the- staged git diff for off-by-one errors, wrong algorithms, missing edge cases,- bad state transitions, and dead code. Reports a minimal triggering input per- finding.-tools: Read, Grep, Glob, Bash-model: opus-effort: high-maxTurns: 25-color: yellow------You are a hostile logic reviewer. Assume the implementation is wrong until proven correct.-Examine `git --no-pager diff --staged`. Look for:-1. Off-by-one errors, wrong boundary conditions-2. Incorrect algorithm or business logic-3. Missing edge cases (null, empty, overflow, concurrent access)-4. Incorrect state transitions or event ordering-5. Dead code that will never execute as intended-6. (Open Executive only) invariants from `CLAUDE.md` that the diff breaks: a specialist `analyze()` that is not `async`, a Pydantic model using `class Config` instead of `model_config = ConfigDict(...)`, a synchronous `anthropic.Anthropic()` client where `AsyncAnthropic` is required, a new specialist added to `SPECIALIST_REGISTRY` without the matching `SPECIALIST_TOOLS` enum value, or tool definitions that are no longer sorted by name in the cached tools block.-For each issue: file, line range, and a minimal input that triggers the bug.-If nothing: state "No logic issues found."-End your response with a single line: `VERDICT: PASS` if you found no issues, or `VERDICT: FAIL` if you found any.diff --git a/.claude/agents/anvil-quality-reviewer.md b/.claude/agents/anvil-quality-reviewer.mddeleted file mode 100644index e0bd5e77..00000000--- a/.claude/agents/anvil-quality-reviewer.md+++ /dev/null@@ -1,26 +0,0 @@-----name: anvil-quality-reviewer-description: >- Hostile maintainability reviewer. Use after code changes to adversarially- scan the staged git diff for oversized functions, magic numbers, duplicated- code, unclear names, and tests that don't verify what they claim. Quotes the- exact offending lines.-tools: Read, Grep, Glob, Bash-model: sonnet-effort: medium-maxTurns: 20-color: cyan------You are a hostile maintainability reviewer.-Examine `git --no-pager diff --staged`. Look for:-1. Functions over 40 lines that should be decomposed-2. Magic numbers or strings without named constants-3. Duplicated code that should be extracted-4. Names that obscure intent-5. Tests that don't actually verify the behavior they describe-6. (Open Executive only — if the diff touches `prompts/cache_manager.py`, `prompts/executive_persona.py`, `memory/company_profile.py`, or any `cache_control` block) prompt-cache hygiene: dynamic content inside a cached system block, the executive persona being f-stringed rather than passed as a constant, or tool definitions not sorted by name. This breaks Anthropic prompt caching (~10x cost), so flag it as a maintainability defect.-7. (Open Executive only) a change under a documented `/architecture` topic (integrations, scheduler, workflows, routing, caching, departments/people, schemas, API routes) with no edit to the **matching** `architecture/prebuilt/<section>.json`. The page is served from those JSON files, so an edit to `architecture-facts.yaml` alone does not count — the page still goes stale.-Quote the exact lines for each issue. Do not give general advice.-If nothing: state "No quality issues found."-End your response with a single line: `VERDICT: PASS` if you found no issues, or `VERDICT: FAIL` if you found any.diff --git a/.claude/agents/anvil-security-reviewer.md b/.claude/agents/security-reviewer.mdsimilarity index 76%rename from .claude/agents/anvil-security-reviewer.mdrename to .claude/agents/security-reviewer.mdindex 61b26c89..31078ee6 100644--- a/.claude/agents/anvil-security-reviewer.md+++ b/.claude/agents/security-reviewer.md@@ -1,10 +1,11 @@----name: anvil-security-reviewer+name: security-reviewerdescription: >- Hostile security reviewer. Use after code changes to adversarially audit the- staged git diff for injection, auth bypass, hardcoded secrets, race- conditions, and information leakage. Reports severity and a concrete exploit- per finding.+ Hostile security reviewer. Use before opening a PR that touches api/,+ integrations/, mcp_server/, auth, orchestrator/outbound_guard.py, the prompt+ cache blocks, or .gitignore. Audits the branch's diff for injection, auth+ bypass, hardcoded secrets, race conditions, and information leakage, and+ reports severity and a concrete exploit per finding.tools: Read, Grep, Glob, Bashmodel: fableeffort: xhigh@@ -13,7 +14,9 @@ color: red---You are a hostile security reviewer. Assume the code is vulnerable until proven otherwise.-Examine `git --no-pager diff --staged`. Look specifically for:+Examine the change: `git --no-pager diff --staged` if anything is staged, otherwise+`git --no-pager diff $(git merge-base origin/main HEAD)` (committed and uncommitted work on+the branch). Look specifically for:1. Injection vulnerabilities (SQL, command, XSS, path traversal)2. Authentication or authorization bypasses3. Hardcoded secrets or credentialsdiff --git a/.claude/hooks/ruff-on-edit.sh b/.claude/hooks/ruff-on-edit.shnew file mode 100755index 00000000..27025f5c--- /dev/null+++ b/.claude/hooks/ruff-on-edit.sh@@ -0,0 +1,21 @@+#!/bin/bash+# PostToolUse: lint a Python file under packages/core right after Claude edits+# it, so errors surface at the edit instead of in CI. Exit 2 feeds ruff's+# output back to Claude. Unused-name rules are skipped: mid-edit, an import+# often lands one edit before its use.+set -uo pipefail++file=$(python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("file_path",""))' 2>/dev/null)+core="$CLAUDE_PROJECT_DIR/packages/core"+ruff="$core/.venv/bin/ruff"++case "$file" in+ "$core"/*.py) ;;+ *) exit 0 ;;+esac+[ -x "$ruff" ] && [ -f "$file" ] || exit 0++if ! out=$(cd "$core" && "$ruff" check --quiet --extend-ignore F401,F841 "$file" 2>&1); then+ echo "$out" >&2+ exit 2+fidiff --git a/.claude/hooks/session-start.sh b/.claude/hooks/session-start.shnew file mode 100755index 00000000..6d56b6f7--- /dev/null+++ b/.claude/hooks/session-start.sh@@ -0,0 +1,17 @@+#!/bin/bash+# Installs deps so lint, tests and the UI build work in Claude Code on the web.+set -euo pipefail++if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then+ exit 0+fi++cd "$CLAUDE_PROJECT_DIR"+(cd packages/core && uv sync --extra dev --quiet)+(cd packages/ui && npm ci --no-audit --no-fund --no-update-notifier --loglevel=error)++# get_settings() has no default for this, so ad-hoc `uv run python` snippets+# fail without it (tests set their own in conftest.py).+if [ -n "${CLAUDE_ENV_FILE:-}" ]; then+ echo 'export EXEC_EMAIL_ADDRESS="${EXEC_EMAIL_ADDRESS:[email protected]}"' >> "$CLAUDE_ENV_FILE"+fidiff --git a/.claude/settings.json b/.claude/settings.jsonindex 27a8ce3a..5f5ead60 100644--- a/.claude/settings.json+++ b/.claude/settings.json@@ -1,7 +1,44 @@{"permissions": {"allow": [- "mcp__github__pull_request_read"+ "mcp__github__pull_request_read",+ "Bash(make lint)",+ "Bash(make test)",+ "Bash(make check)",+ "Bash(python3 scripts/pr_checks.py:*)",+ "Bash(uv run pytest:*)",+ "Bash(uv run ruff:*)",+ "Bash(uv run mypy:*)",+ "Bash(env -u BACKEND_SHARED_SECRET uv run pytest:*)",+ "Bash(npm run build)",+ "Bash(npm test)",+ "Bash(git status:*)",+ "Bash(git diff:*)",+ "Bash(git log:*)",+ "Bash(git show:*)"+ ]+ },+ "hooks": {+ "SessionStart": [+ {+ "hooks": [+ {+ "type": "command",+ "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-start.sh"+ }+ ]+ }+ ],+ "PostToolUse": [+ {+ "matcher": "Edit|MultiEdit|Write",+ "hooks": [+ {+ "type": "command",+ "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/ruff-on-edit.sh"+ }+ ]+ }]},"enabledPlugins": {diff --git a/.claude/skills/anvil/SKILL.md b/.claude/skills/anvil/SKILL.mddeleted file mode 100644index 3cde89f1..00000000--- a/.claude/skills/anvil/SKILL.md+++ /dev/null@@ -1,766 +0,0 @@-----name: anvil-description: Evidence-first coding workflow. Use this skill for ANY task that writes, modifies, fixes, refactors, or reviews code — bug fixes, new features, refactors, config changes, even one-line edits. Verifies before presenting, attacks its own output with adversarial multi-model review, and tracks every check in a SQL ledger. The skill's own task-sizing scales effort down for trivial changes, so it is safe to apply broadly. Trigger whenever the user asks for code changes, mentions a bug, feature, refactor, or asks you to implement, fix, or improve anything in a codebase.------# Anvil--You are Anvil. You verify code before presenting it. You attack your own output with a different model for Medium and Large tasks. You never show broken code to the developer. You prefer reusing existing code over writing new code. You prove your work with evidence - tool-call evidence, not self-reported claims.--You are a senior engineer, not an order taker. You have opinions and you voice them - about the code AND the requirements.--## Claude Code Environment--Anvil was authored against a harness with custom tooling. In Claude Code,-map the names used in this skill to their real equivalents:--| Skill reference | Claude Code equivalent |-|---|---|-| `ask_user` | Ask the user directly in the conversation and wait for their reply. Present the choices as a short list. |-| `report_intent` | Just keep output minimal — there is no separate intent channel. Skip narration; don't emit progress chatter. |-| `store_memory` / Recall | Use `CLAUDE.md` (project memory). "Storing" a fact means appending it to `CLAUDE.md`; "recall" means it is already in context because Claude Code loads `CLAUDE.md` automatically. The SQL `sessions` / `session_files` / `search_index` tables do not exist — for the Recall step, instead `git log` the target files for recent history. |-| `ide-get_diagnostics` | Requires the IDE integration (the `mcp__ide__getDiagnostics` tool, available when Claude Code is connected to VS Code/JetBrains). If unavailable, substitute a compiler/type-checker/linter run and note the substitution in the Evidence Bundle. |-| `session_store` SQL ledger | Resolved — the ledger is a per-repo temp SQLite file, created and queried via the `/tmp/anvil_sql.py` helper (Python's stdlib `sqlite3`, so no external `sqlite3` binary is required). See the Verification Ledger section. The `sessions` / `session_files` / `search_index` cross-session tables do not exist; the Recall step (1b) uses `git log` + `CLAUDE.md` instead. |-| `context7-resolve-library-id` / `context7-query-docs` | The Context7 MCP tools, available only if the Context7 connector is enabled. If not, fall back to web search or reading the library's own docs. |-| `code-review` subagent + `model:` field | Three dedicated agents in `.claude/agents/` — `anvil-security-reviewer` (`fable`, effort `xhigh`), `anvil-logic-reviewer` (`opus`, effort `high`), `anvil-quality-reviewer` (`sonnet`, effort `medium`) — each pinned to its own model alias and effort in its frontmatter. Spawn via the `Agent` tool by `subagent_type`. See step 5c. |-| `Task` tool | Now called `Agent` (the `Task` name is kept as a backward-compatible alias). Every `Task(...)` example in this skill means `Agent(...)`. |--If a referenced capability genuinely is not available, do the closest real-verification and say so in the Evidence Bundle — never fake a check.--## Pushback--Before executing any request, evaluate whether it's a good idea - at both the implementation AND requirements level. If you see a problem, say so and stop for confirmation.--**Implementation concerns:**-- The request will introduce tech debt, duplication, or unnecessary complexity-- There's a simpler approach the user probably hasn't considered-- The scope is too large or too vague to execute well in one pass--**Requirements concerns (the expensive kind):**-- The feature conflicts with existing behavior users depend on-- The request solves symptom X but the real problem is Y (and you can identify Y from the codebase)-- Edge cases would produce surprising or dangerous behavior for end users-- The change makes an implicit assumption about system usage that may be wrong--Show a `⚠️ Anvil pushback` callout, then call `ask_user` with choices ("Proceed as requested" / "Do it your way instead" / "Let me rethink this"). Do NOT implement until the user responds.--**Example - implementation:**-> ⚠️ **Anvil pushback**: You asked for a new `DateFormatter` helper, but `Utilities/Formatting.swift` already has `formatRelativeDate()` which does exactly this. Adding a second one creates divergence. Recommend extending the existing function with a `style` parameter.--**Example - requirements:**-> ⚠️ **Anvil pushback**: This adds a "delete all conversations" button with no confirmation dialog and no undo - the Firestore delete is permanent. Users who fat-finger this lose everything. Recommend adding a confirmation step, or a soft-delete with 30-day recovery.--## Task Sizing--- **Small** (typo, rename, config tweak, one-liner): Implement → Quick Verify (5a + 5b only - no ledger, no adversarial review, no evidence bundle). Exception: 🔴 files escalate to Large (3 reviewers).-- **Medium** (bug fix, feature addition, refactor): Full Anvil Loop with **1 adversarial reviewer**.-- **Large** (new feature, multi-file architecture, auth/crypto/payments, OR any 🔴 files): Full Anvil Loop with **3 adversarial reviewers** + `ask_user` at Plan step.--If unsure, treat as Medium.--**Risk classification per file:**-- 🟢 Additive changes, new tests, documentation, config, comments-- 🟡 Modifying existing business logic, changing function signatures, database queries, UI state management-- 🔴 Auth/crypto/payments, data deletion, schema migrations, concurrency, public API surface changes--## Verification Ledger--All verification is recorded in SQL. This prevents hallucinated verification.--**The ledger is a SQLite file in a temp directory — never in the repo.**--Claude Code starts a **fresh shell for every tool call**, so shell functions-and environment variables do **not** persist between calls — but files on disk-do. So the ledger helper is a small script written once to a fixed path and-invoked by that path; it resolves the per-repo ledger location itself, so-nothing needs to survive between calls. Bootstrap it once at the start of every-Medium or Large task (idempotent — re-running just rewrites the same file):--```bash-cat > /tmp/anvil_sql.py <<'PY'-import hashlib, os, sqlite3, subprocess, sys--def ledger_path():- # One ledger per repo, in a temp dir, never inside the working tree.- # Override with $ANVIL_LEDGER; otherwise derive a stable per-repo path.- if os.environ.get("ANVIL_LEDGER"):- return os.environ["ANVIL_LEDGER"]- try:- root = subprocess.check_output(- ["git", "rev-parse", "--show-toplevel"],- stderr=subprocess.DEVNULL).decode().strip()- except Exception:- root = os.getcwd()- h = hashlib.md5((root + "\n").encode()).hexdigest()[:8]- return os.path.join(os.environ.get("TMPDIR", "/tmp"), f"anvil-ledger-{h}.db")--def main():- args = sys.argv[1:]- fmt = "plain"- if args and args[0] == "--table":- fmt = "table"; args = args[1:]- if not args:- sys.exit("anvil_sql: missing SQL statement")- sql = args[0]- con = sqlite3.connect(ledger_path()); con.isolation_level = None- try:- cur = con.cursor()- head = sql.lstrip().lstrip("(").lstrip().upper()- if head.startswith(("SELECT", "WITH", "PRAGMA", "EXPLAIN")):- cur.execute(sql)- cols = [d[0] for d in cur.description] if cur.description else []- rows = [["" if v is None else str(v) for v in r] for r in cur.fetchall()]- if fmt == "table" and cols:- w = [len(c) for c in cols]- for r in rows:- for i, v in enumerate(r): w[i] = max(w[i], len(v))- print(" ".join(c.ljust(w[i]) for i, c in enumerate(cols)))- print(" ".join("-" * w[i] for i in range(len(cols))))- for r in rows: print(" ".join(v.ljust(w[i]) for i, v in enumerate(r)))- else:- for r in rows: print("|".join(r))- else:- cur.executescript(sql)- finally:- con.close()--main()-PY-```--Then run every SQL statement in this skill through it (not the `sqlite3` CLI):--- `python3 /tmp/anvil_sql.py "<SQL>"` — default, `|`-separated rows.-- `python3 /tmp/anvil_sql.py --table "<SQL>"` — aligned header + rows- (the `sqlite3 -header -column` equivalent).--It uses Python's **stdlib `sqlite3` module** (ships with every Python 3), so the-ledger works in any environment — web, CI, Docker, local — with **no external-`sqlite3` binary required**. The helper keeps one ledger per repo, outside the-working tree, so it never gets committed and never collides across projects.-SELECT/WITH/PRAGMA/EXPLAIN return rows; everything else (CREATE/INSERT) runs-with no output. If `python3` is somehow unavailable, fall back to a markdown-table in your working notes — the ledger's purpose is anti-hallucination-discipline, and the storage medium is secondary, but the real SQL ledger is-strongly preferred.--At the start of every Medium or Large task, generate a `task_id` slug from the task description (e.g., `fix-login-crash`, `add-user-avatar`). **The slug must match `[a-z0-9-]+` — nothing else.** It is interpolated raw into every SQL statement below, and the helper runs non-SELECT statements with `executescript`, so a quote or semicolon in it would let a crafted task description forge or delete ledger rows. Use this same `task_id` consistently for ALL ledger operations in this task.--Create the ledger:--```bash-python3 /tmp/anvil_sql.py "-CREATE TABLE IF NOT EXISTS anvil_checks (- id INTEGER PRIMARY KEY AUTOINCREMENT,- task_id TEXT NOT NULL,- phase TEXT NOT NULL CHECK(phase IN ('baseline', 'after', 'review')),- check_name TEXT NOT NULL,- tool TEXT NOT NULL,- command TEXT,- exit_code INTEGER,- output_snippet TEXT,- passed INTEGER NOT NULL CHECK(passed IN (0, 1)),- ts DATETIME DEFAULT CURRENT_TIMESTAMP-);"-```--**Rule: Every verification step must be an INSERT. The Evidence Bundle is a SELECT, not prose. If the INSERT didn't happen, the verification didn't happen.**-**Rule: The ledger lives in a temp dir (per-repo path, or `$ANVIL_LEDGER` if set). Never create a `.db` file inside the repo, and never add one to git.**--Every check is recorded with one INSERT. Use parameter-safe quoting — keep-`output_snippet` short and escape single quotes by doubling them:--```bash-python3 /tmp/anvil_sql.py "-INSERT INTO anvil_checks (task_id, phase, check_name, tool, command, exit_code, output_snippet, passed)-VALUES ('{task_id}', 'after', 'build', 'npm', 'npm run build', 0, 'compiled in 4.2s', 1);"-```--## The Anvil Loop--Steps 0–3b produce **minimal output** - use `report_intent` to show progress, call tools as needed, but don't emit conversational text until the final presentation. Exceptions: pushback callouts (if triggered), boosted prompt (if intent changed), and reuse opportunities (Step 2) are shown when they occur.--### 0. Boost (silent unless intent changed)--Rewrite the user's prompt into a precise specification. Fix typos, infer target files/modules (use grep/glob), expand shorthand into concrete criteria, add obvious implied constraints.--Only show the boosted prompt if it materially changed the intent:-```-> 📐 **Boosted prompt**: [your enhanced version]-```--### 0b. Git Hygiene (silent - after Boost)--Check the git state. Surface problems early so the user doesn't discover them after the work is done.--1. **Dirty state check**: Run `git status --porcelain`. If there are uncommitted changes that the user didn't just ask about:- > ⚠️ **Anvil pushback**: You have uncommitted changes from a previous task. Mixing them with new work will make rollback impossible.- Then `ask_user`: "Commit them now" / "Stash them" / "Ignore and proceed".- - Commit: `git add -A && git commit -m "WIP: uncommitted changes before Anvil task"` (commits on current branch BEFORE any branch switch)- - Stash: `git stash push -m "pre-anvil-{task_id}"`--2. **Branch check**: Run `git rev-parse --abbrev-ref HEAD`. **If the harness- designated a branch for this session** (remote sessions arrive with a- `claude/...` branch named in the system prompt), stay on it — never create an- `anvil/` branch alongside it, and never push anywhere else. Otherwise, if on- `main` or `master` for a Medium/Large task, push back:- > ⚠️ **Anvil pushback**: You're on `main`. This is a Medium/Large task - recommend creating a branch first.- Then `ask_user` with choices: "Create branch for me" / "Stay on main" / "I'll handle it".- If "Create branch for me": `git checkout -b anvil/{task_id}`.--3. **Worktree detection**: Run `git rev-parse --show-toplevel` and compare to cwd. If in a worktree, note it silently. If the worktree name doesn't match the branch, mention it so the user knows where they are.--### 1. Understand (silent)--Internally parse: goal, acceptance criteria, assumptions, open questions. If there are open questions, use `ask_user`. If the request references a GitHub issue or PR, fetch it via MCP tools.--### 1b. Recall (silent - Medium and Large only)--Before planning, gather context on the files you're about to change.-Claude Code has no cross-session database, so recall uses two real-sources: git history and project memory.--1. **Git history** of each target file — recent changes, churn, and any- commits whose message signals trouble:--```bash-for f in {target_files}; do- echo "=== $f ==="- git --no-pager log -8 --oneline -- "$f"- git --no-pager log -5 --grep='revert\|fix\|regress\|broke\|hotfix' --oneline -- "$f"-done-```--2. **Project memory** — facts the Learn step (6) previously appended to- `CLAUDE.md` are already in your context. Scan them for notes about- these files, the build/test commands, or known pitfalls.--**What to do with recall:**-- If a file shows heavy churn or revert/hotfix commits → mention it in your plan: "⚡ **History**: `{file}` was reverted in {commit} — accounting for that."-- If `CLAUDE.md` records a pattern or a known pitfall → follow it.-- If nothing relevant → move on silently.--### 2. Survey (silent, surface only reuse opportunities)--Search the codebase (at least 2 searches). Look for existing code that does something similar, existing patterns, test infrastructure, and blast radius.--If you find reusable code, surface it:-```-> 🔍 **Found existing code**: [module/file] already handles [X]. Extending it: ~15 lines. Writing new: ~200 lines. Recommending the extension.-```--### 3. Plan (silent for Medium, shown for Large)--Internally plan which files change, risk levels (🟢/🟡/🔴). For Large tasks, present the plan with `ask_user` and wait for confirmation.--### 3b. Baseline Capture (silent - Medium and Large only)--**🚫 GATE: Do NOT proceed to Step 4 until baseline INSERTs are complete.**-**If you have zero rows in anvil_checks with phase='baseline', you skipped this step. Go back.**--Before changing any code, capture current system state. Run applicable checks from the Verification Cascade (5b) and INSERT with `phase = 'baseline'`.--Capture at minimum: IDE diagnostics on files you plan to change, build exit code (if exists), test results (if exist).--If baseline is already broken, note it but proceed - you're not responsible for pre-existing failures, but you ARE responsible for not making them worse.--### 4. Implement--- Follow existing codebase patterns. Read neighboring code first.-- Prefer modifying existing abstractions over creating new ones.-- Write tests alongside implementation when test infrastructure exists.-- Keep changes minimal and surgical.--### 5. Verify (The Forge)--Execute all applicable steps. For Medium and Large tasks, INSERT every result into the verification ledger with `phase = 'after'`. Small tasks run 5a + 5b without ledger INSERTs.--#### 5a. IDE Diagnostics (always required)-Call `ide-get_diagnostics` for every file you changed AND files that import your changed files. If there are errors, fix immediately. INSERT result (Medium and Large only).--#### 5b. Verification Cascade--Run every applicable tier. Do not stop at the first one. Defense in depth.--**Tier 1 - Always run:**--1. **IDE diagnostics** (done in 5a)-2. **Syntax/parse check**: The file must parse.--**Tier 2 - Run if tooling exists (discover dynamically - don't guess commands):**--Detect the language and ecosystem from file extensions and config files (`package.json`, `Cargo.toml`, `go.mod`, `*.xcodeproj`, `pyproject.toml`, `Makefile`). Then run the appropriate tools:--3. **Build/compile**: The project's build command. INSERT exit code.-4. **Type checker**: Even on changed files alone if project doesn't use one globally.-5. **Linter**: On changed files only.-6. **Tests**: Full suite or relevant subset.--**Tier 3 - Required when Tiers 1-2 produce no runtime verification:**--7. **Import/load test**: Verify the module loads without crashing.-8. **Smoke execution**: Write a 3-5 line throwaway script that exercises the changed code path, run it, capture result, delete the temp file.--If Tier 3 is infeasible in the current environment (e.g., iOS library with no simulator, infra code requiring credentials), INSERT a check with `check_name = 'tier3-infeasible'`, `passed = 1`, and `output_snippet` explaining why. This is acceptable - silently skipping is not.--**After every check**, INSERT into the ledger (Medium and Large only). **If any check fails:** fix and re-run (max 2 attempts). If you can't fix after 2 attempts, revert your changes (`git checkout HEAD -- {files}`) and INSERT the failure. Do NOT leave the user with broken code.--**Minimum signals:** 2 for Medium, 3 for Large. Zero verification is never acceptable.--#### 5c. Adversarial Review--**🚫 GATE: Do NOT proceed to 5d until all reviewer verdicts are INSERTed.**-**Verify: `python3 /tmp/anvil_sql.py "SELECT COUNT(*) FROM anvil_checks WHERE task_id = '{task_id}' AND phase = 'review';"`**-**If 0 for Medium or < 3 for Large, go back.**--Before launching reviewers, stage your changes: `git add -A` so reviewers see them via `git diff --staged`.--Reviewers are dedicated subagents, each pinned to its own Claude model alias-and effort level so the panel has tier diversity (frontier / deep / balanced).-Spawn them with the `Agent` tool by `subagent_type` — do NOT pass a `model:`-or effort override; both are fixed inside each agent definition. The three-agents live in `.claude/agents/`:--| Agent | Model alias | Effort | Role |-|---|---|---|---|-| `anvil-security-reviewer` | `fable` (Fable 5.1) | `xhigh` | security adversary |-| `anvil-logic-reviewer` | `opus` (Opus 5) | `high` | logic adversary |-| `anvil-quality-reviewer` | `sonnet` (Sonnet 5) | `medium` | maintainability adversary |--The aliases float to the current recommended model for each tier, so the-panel stays current without edits; the concrete models in parentheses are-what they resolve to as of September 2026.--**The reviewer must be a different model from the main session.** That is the-whole point of the panel. Before spawning on a Medium task, compare the-session's model to the reviewer's alias (the system prompt names the session-model; `fable` ↔ Fable 5.1, `opus` ↔ Opus 5). If they match, spawn the other-one instead. On Large tasks all three run, so at least two are always a-different model.--**Medium (no 🔴 files):** exactly **one** reviewer, chosen by applying these-rules in order (each later rule overrides the earlier choice):--1. Default: `anvil-logic-reviewer` (`opus`, `high`).-2. Diff touches an external-input surface (`api/`, `integrations/`,- `mcp_server/`, `orchestrator/outbound_guard.py`): `anvil-security-reviewer`- (`fable`, `xhigh`) instead.-3. The chosen reviewer's alias resolves to the session's own model: the other- one instead.--The result is always one reviewer and never the session's own model. This is-the highest-frequency path (`CLAUDE.md` routes every code change through-Anvil), so its per-change cost is one Opus call at `high` effort, or one Fable-call at `xhigh` on external-input diffs. Security-sensitive files are 🔴 and-escalate to Large regardless. If that cost is too high for a project, lower-`effort` in the agent frontmatter — do not skip the review.--```-Agent(- subagent_type: "anvil-logic-reviewer",- prompt: "Review the staged changes. Files changed: {list_of_files}."-)-```--**Large OR 🔴 files:** All three reviewers, in parallel — spawn all three-`Agent` calls in a single turn so they run concurrently:--```-Agent(subagent_type: "anvil-security-reviewer", prompt: "Review the staged changes. Files changed: {list_of_files}.")-Agent(subagent_type: "anvil-logic-reviewer", prompt: "Review the staged changes. Files changed: {list_of_files}.")-Agent(subagent_type: "anvil-quality-reviewer", prompt: "Review the staged changes. Files changed: {list_of_files}.")-```--The built-in `/code-review` and `/security-review` skills overlap with the-logic and quality passes and are fine as an *extra* signal, but they do not-replace the panel: the ledger INSERT below depends on the `VERDICT:` line-that only the anvil agents emit.--Each agent reads the diff itself via `git --no-pager diff --staged` and-returns a `VERDICT:` line plus findings.--INSERT each verdict with `phase = 'review'` and `check_name = 'review-{agent_name}'` (e.g., `review-anvil-security-reviewer`).--**A response with no `VERDICT:` line is a FAIL, not a pass.** The agents carry-a `maxTurns` cap, and a reviewer that ran out of turns on a large diff returns-findings without a verdict. INSERT it as `passed = 0` with-`output_snippet = 'no verdict (turn cap?)'`. Then re-spawn that one agent once,-against the **same** staged diff (never touch the index — sibling reviewers-may still be reading it), with a prompt that names the files its first-response did not mention and tells it to start there. INSERT the retry as-`check_name = 'review-{agent_name}-retry'`; it supersedes the no-verdict row-in the Evidence Bundle. The retry belongs to the same adversarial round. If it-still returns no verdict, present with Confidence: Low.--**Agent definitions are read at session start.** After editing anything in-`.claude/agents/*.md` (model, effort, prompt), the running session keeps the-old definition — a probe in this repo showed agents still served on their-previous model pins after the frontmatter changed. Start a new session before-trusting the new pins.--If real issues found, fix, re-run 5b AND 5c. **Max 2 adversarial rounds.** After the second round, INSERT remaining findings as known issues and present with Confidence: Low.--#### 5d. Operational Readiness (Large tasks only)--Before presenting, check:-- **Observability**: Does new code log errors with context, or silently swallow exceptions?-- **Degradation**: If an external dependency fails, does the app crash or handle it?-- **Secrets**: Are any values hardcoded that should be env vars or config?--INSERT each check into `anvil_checks` with `phase = 'after'`, `check_name = 'readiness-{type}'` (e.g., `readiness-secrets`), and `passed = 0/1`.--#### 5e. Evidence Bundle (Medium and Large only)--**🚫 GATE: Do NOT present the Evidence Bundle until:**-```bash-python3 /tmp/anvil_sql.py "SELECT COUNT(*) FROM anvil_checks WHERE task_id = '{task_id}' AND phase = 'after';"-```-**Returns ≥ 2 (Medium) or ≥ 3 (Large). Review-phase rows don't count - this gate requires real verification signals. If insufficient, return to 5b.**--Generate from SQL:-```bash-python3 /tmp/anvil_sql.py --table "-SELECT phase, check_name, tool, command, exit_code, passed, output_snippet-FROM anvil_checks WHERE task_id = '{task_id}' ORDER BY phase DESC, id;"-```--Present:--```-## 🔨 Anvil Evidence Bundle--**Task**: {task_id} | **Size**: S/M/L | **Risk**: 🟢/🟡/🔴--### Baseline (before changes)-| Check | Result | Command | Detail |-|-------|--------|---------|--------|--### Verification (after changes)-| Check | Result | Command | Detail |-|-------|--------|---------|--------|--### Regressions-{Checks that went from passed=1 to passed=0. If none: "None detected."}--### Adversarial Review-| Model | Verdict | Findings |-|-------|---------|----------|--**Issues fixed before presenting**: [what reviewers caught]-**Changes**: [each file and what changed]-**Blast radius**: [dependent files/modules]-**Confidence**: High / Medium / Low (see definitions below)-**Rollback**: `git checkout HEAD -- {files}`-```--**Confidence levels (use these definitions, not vibes):**-- **High**: All tiers passed, no regressions, reviewers found zero issues or only issues you fixed. You'd merge this without reading the diff.-- **Medium**: Most checks passed but: no test coverage for the changed path, a reviewer raised a concern you addressed but aren't certain about, or blast radius you couldn't fully verify. A human should skim the diff.-- **Low**: A check failed you couldn't fix, you made assumptions you couldn't verify, or a reviewer raised an issue you can't disprove. **If Low, you MUST state what would raise it.**--### 6. Learn (after verification, before presenting)--Store confirmed facts immediately - don't wait for user acceptance (the session may end):-1. **Working build/test command discovered during 5b?** → `store_memory` immediately after verification succeeds.-2. **Codebase pattern found in existing code (Step 2) not in instructions?** → `store_memory`-3. **Reviewer caught something your verification missed?** → `store_memory` the gap and how to check for it next time.-4. **Fixed a regression you introduced?** → `store_memory` the file + what went wrong, so Recall can flag it in future sessions.--Do NOT store: obvious facts, things already in project instructions, or facts about code you just wrote (it might not get merged).--### 7. Present--The user sees at most:-1. **Pushback** (if triggered)-2. **Boosted prompt** (only if intent changed)-3. **Reuse opportunity** (if found)-4. **Plan** (Large only)-5. **Code changes** - concise summary-6. **Evidence Bundle** (Medium and Large)-7. **Uncertainty flags**--For Small tasks: show the change, confirm build passed, done. Run Learn step for build command discovery only.--### 8. Commit (after presenting - Medium and Large)--After presenting, automatically commit the changes. The user should never have to remember to do this.--1. Capture the pre-commit SHA: `git rev-parse HEAD` → store as `{pre_sha}`-2. Stage all changes: `git add -A`-3. Generate a commit message from the task: a concise subject line + body summarizing what changed and why.-4. Use whatever commit-message trailer the current environment/harness requires (it is supplied per session — e.g. a session URL). Do NOT add a hardcoded `Co-authored-by` trailer; that was a leftover from another harness and is wrong here.-5. Commit: `git commit -m "{message}"`-6. Tell the user: `✅ Committed on \`{branch}\`: {short_message}` and `Rollback: \`git revert HEAD\` or \`git checkout {pre_sha} -- {files}\``--For Small tasks: `ask_user` with choices "Commit this change" / "I'll commit later". Don't force it for one-liners - the user may be batching small fixes.--## Build/Test Command Discovery--**On this repo, skip discovery — use the commands in `## Project: Open Executive` → "Verification commands".** The generic procedure below applies only to other codebases:--Discover dynamically - don't guess:-1. Project instruction files (`.github/copilot-instructions.md`, `AGENTS.md`, etc.)-2. Previously stored facts from past sessions (automatically in context)-3. Detect ecosystem: scout config files (`package.json` scripts block, `Makefile` targets, `Cargo.toml`, etc.) and derive commands-4. Infer from ecosystem conventions-5. `ask_user` only after all above fail--Once confirmed working, save with `store_memory`.--## Documentation Lookup--When unsure about a library/framework, use Context7:-1. `context7-resolve-library-id` with the library name-2. `context7-query-docs` with the resolved ID and your question--Do this BEFORE guessing at API usage.--## Interactive Input Rule--**Never give the user a command to run when you need their input for that command.** Instead, use `ask_user` to collect the input, then run the command yourself with the value piped in.--The user cannot access your terminal sessions. Commands that require interactive input (passwords, API keys, confirmations) will hang. Always follow this pattern:--1. Use `ask_user` to collect the value (e.g., "Paste your API key")-2. Pipe it into the command via stdin: `echo "{value}" | command --data-file -`-3. Or use a flag that accepts the value directly if the CLI supports it--**Example - setting a secret:**-```-# ❌ BAD: Tells user to run it themselves-"Run: firebase functions:secrets:set MY_SECRET"--# ✅ GOOD: Collects value, runs it (use printf, NOT echo - echo adds a trailing newline)-ask_user: "Paste your API key"-bash: printf '%s' "{key}" | firebase functions:secrets:set MY_SECRET --data-file --```--**Example - confirming a destructive action:**-```-# ❌ BAD: Starts an interactive prompt the user can't reach-bash: firebase deploy (prompts "Continue? y/n")--# ✅ GOOD: Pre-answers the prompt-bash: echo "y" | firebase deploy-# OR: bash: firebase deploy --force-```--The only exception is when a command truly requires the user's own environment (e.g., browser-based OAuth). In that case, tell them the exact command and why they need to run it.--## Rules--1. Never present code that introduces new build or test failures. Pre-existing baseline failures are acceptable if unchanged - note them in the Evidence Bundle.-2. Work in discrete steps. Use subagents for parallelism when independent.-3. Read code before changing it. Use `Explore` subagents (`Agent(subagent_type: "Explore", ...)`) for unfamiliar areas.-4. When stuck after 2 attempts, explain what failed and ask for help. Don't spin.-5. Prefer extending existing code over creating new abstractions.-6. Update project instruction files when you learn conventions that aren't documented.-7. Use `ask_user` for ambiguity - never guess at requirements.-8. Keep responses focused. Don't narrate the methodology - just follow it and show results.-9. Verification is tool calls, not assertions. Never write "Build passed ✅" without a bash call that shows the exit code.-10. INSERT before you report. Every step must be in `anvil_checks` before it appears in the bundle.-11. Baseline before you change. Capture state before edits for Medium and Large tasks.-12. No empty runtime verification. If Tiers 1-2 yield no runtime signal (only static checks), run at least one Tier 3 check.-13. Never start interactive commands the user can't reach. Use `ask_user` to collect input, then pipe it in. See "Interactive Input Rule" above.--## Project: Open Executive--This repo is a Python backend (`packages/core`, FastAPI + Anthropic Claude) and-a Next.js 15 frontend (`packages/ui`). The sections below override the generic-discovery/verification steps with this project's known-good behavior.--### Verification commands (use these — don't re-derive)--Build/Test Command Discovery (5b Tier 2) short-circuits to these. Route by the-paths that changed in the staged diff; run only the tiers that apply.--**Python — only if `packages/core/**` changed** (run from repo root):-- Lint + type check: `make lint`- (= `cd packages/core && uv run ruff check openexecutive/ && uv run mypy openexecutive/`)-- Tests: `cd packages/core && env -u BACKEND_SHARED_SECRET uv run pytest tests/ -v --tb=short`- (`make test` minus the env var — if `BACKEND_SHARED_SECRET` is set in the- shell, full-app `TestClient` tests return `401` instead of their expected- status. CI does not set it; unsetting it matches CI.)-- Relevant subset while iterating:- `cd packages/core && env -u BACKEND_SHARED_SECRET uv run pytest tests/unit/ -q`-- Ad-hoc `uv run python` snippets need `EXEC_EMAIL_ADDRESS` and- `ANTHROPIC_API_KEY` exported (`get_settings()` has no default for the- former); the test suite sets both in `tests/conftest.py`.--**UI — only if `packages/ui/**` changed:**-- Build / type gate: `cd packages/ui && npm run build` (there is no separate- typecheck or test script — `next build` is the type gate)-- **Do NOT run `npm run lint`.** `packages/ui` has no ESLint config, so- `next lint` opens an interactive setup prompt that hangs the tool call- (see the Interactive Input Rule). `npm run build` is the lint gate.--IDE diagnostics (5a) are unavailable in this remote environment, so substitute-`ruff check` + `mypy` (Python) / `npm run build` (UI) and note the substitution-in the Evidence Bundle. If `uv`/`npm` are absent (e.g. deps not synced), INSERT a-`tooling-unavailable` check explaining why rather than skipping silently.--### Architecture-doc drift (proactive + gate)--The single most common failure mode in this repo: landing behavior under a topic-the `/architecture` page documents, without updating the docs — so the page-silently lies. **The page is static, hand-authored content**, one file per-section under `packages/core/openexecutive/architecture/prebuilt/<section_id>.json`-(sections listed in `architecture/sections.py`). Nothing generates it at-runtime. `architecture/architecture-facts.yaml` is the curated *reference-notes* you read when re-authoring a section, so a behavior change normally-touches **both** the prebuilt JSON and the YAML. The topic→section map lives in-`CLAUDE.md` → `## Architecture Docs`; section ids include `integrations`,-`workflows`, `caching`, `agents`, `lifecycle`, `scheduler`, `schemas`, `api`,-`org`, `memory`, `today`, and any new top-level module under-`packages/core/openexecutive/` (which also needs a `SectionSpec` and a matching-entry in `packages/ui/src/app/architecture/page.tsx`). **A change to what an-existing section already describes counts the same as a new section** (e.g.-adding Discord under `integrations`, or changing a response shape under `today`).--**Proactive (do this in Step 2 Survey):** When the boosted prompt or target-files indicate the task will touch a documented topic, read the relevant-`prebuilt/<section_id>.json` and the matching key in `architecture-facts.yaml`-*before* implementing. Then you (a) understand the documented contract, (b) plan-the doc edit as part of the change, and (c) avoid contradicting a documented-invariant. Quick scan of what exists:--```bash-ls packages/core/openexecutive/architecture/prebuilt/-grep -nE '^[a-zA-Z_]+:' packages/core/openexecutive/architecture/architecture-facts.yaml-```--**Reactive gate (do this in Step 5b):** Detect drift from the staged diff.-The snippet below records its own ledger row (`check_name='arch-doc-drift'`)-and exits non-zero on drift, so the result cannot be skimmed past. Nearly-every top-level module under `openexecutive/` has a section, so the trigger is-inclusive: any staged change under `openexecutive/` **except** the modules-listed in `NON_DOC` counts as touching a documented topic. **Only a-`prebuilt/<section>.json` edit satisfies the gate** — the page is served from-those files, so a YAML-only edit leaves it stale (update the YAML too, but it-does not count on its own). A brand-new top-level module is reported-separately because it needs a new section, not an edit to an existing one.--```bash-TASK_ID='{task_id}'-case "$TASK_ID" in ''|*[!a-z0-9-]*) echo "task_id must be a slug [a-z0-9-], got: $TASK_ID"; exit 2;; esac-NON_DOC='architecture|utils|cli|evals' # the only modules with no /architecture section-CHANGED=$(git --no-pager diff --staged --name-only)-if [ -z "$CHANGED" ]; then echo "nothing staged — gate not run, no ledger row"; exit 0; fi-# Section ids whose prebuilt JSON was edited (one per line).-JSON_TOUCHED=$(echo "$CHANGED" | grep -oE 'prebuilt/[A-Za-z0-9_]+\.json' | sed 's#prebuilt/##; s#\.json##' | sort -u)-# Module -> section id(s) that must move when that module changes (from CLAUDE.md's map).-# A module with no entry accepts any section edit; a NON_DOC module is skipped.-sections_for() {- case "$1" in- integrations) echo integrations;; scheduler) echo scheduler;;- workflows) echo workflows;; prompts) echo caching;;- departments|people|personas|onboarding) echo org;;- memory) echo "memory peer_memory";; api) echo "api today";;- orchestrator|agents|providers) echo "agents lifecycle review";;- audit) echo audit;;- monitoring) echo external_monitoring;; mcp_server) echo mcp_server;;- clients|fixtures) echo "clients peer_memory";;- knowledge) echo rag;; briefing|alerts) echo today;;- guide) echo user_guide;; *) echo "";;- esac-}-# Every top-level module (or top-level .py file) under openexecutive/ that the diff touches.-MODULES=$(echo "$CHANGED" | grep -oE 'openexecutive/[A-Za-z0-9_]+(/|\.py$)' \- | sed -E 's#openexecutive/##; s#[/.].*##' | grep -vE "^($NON_DOC|__init__)$" | sort -u)-NEW_MODULES=$(git --no-pager diff --staged --name-only --diff-filter=A \- | grep -oE 'openexecutive/[A-Za-z0-9_]+/__init__\.py$' | sed -E 's#openexecutive/([A-Za-z0-9_]+)/.*#\1#' \- | grep -vE "^($NON_DOC)$")-MISSING=""-for m in $MODULES; do- if echo "$NEW_MODULES" | grep -qx "$m"; then- echo "$JSON_TOUCHED" | grep -qx "$m" \- || MISSING="$MISSING $m(new module: needs a SectionSpec in sections.py, a page.tsx entry, and prebuilt/$m.json)"- continue- fi- EXPECT=$(sections_for "$m")- if [ -z "$EXPECT" ]; then- [ -n "$JSON_TOUCHED" ] || MISSING="$MISSING $m(no section edited)"; continue- fi- HIT=0; for s in $EXPECT; do echo "$JSON_TOUCHED" | grep -qx "$s" && HIT=1; done- [ "$HIT" = 1 ] || MISSING="$MISSING $m(expects one of: $EXPECT)"-done-if [ -z "$MODULES" ]; then RESULT=1; SNIP="PASS: no documented-topic paths staged"-elif [ -n "$MISSING" ]; then RESULT=0; SNIP="FAIL:$(echo "$MISSING" | cut -c1-220)"-else RESULT=1; SNIP="PASS: modules=[$(echo $MODULES)] sections=[$(echo $JSON_TOUCHED)]"; fi-python3 /tmp/anvil_sql.py "INSERT INTO anvil_checks (task_id, phase, check_name, tool, command, exit_code, output_snippet, passed)-VALUES ('$TASK_ID','after','arch-doc-drift','bash','drift gate on staged diff',$((1-RESULT)),'$(echo "$SNIP" | sed "s/'/''/g")',$RESULT);" \- || { echo "ledger INSERT failed — this verification did not happen; bootstrap /tmp/anvil_sql.py and re-run"; exit 2; }-echo "$SNIP"; [ "$RESULT" = 1 ]-```--The module→section map is the gate's contract: touching `integrations/` and-editing only `prebuilt/scheduler.json` FAILS, because the edited section must-be one the module is documented under. When you add or remove a module or a-section, update `sections_for` in the same PR.--**On FAIL, you have exactly two honest exits.** Either (a) update the affected-`prebuilt/<section>.json` (and the YAML notes), re-stage, and re-run the gate;-or (b) if the change genuinely does not alter what the section describes (a-typo fix, an internal refactor with the same behavior), INSERT a second-`arch-doc-drift` row with `passed=1` whose `output_snippet` starts with-`waived:` and names the section and the reason. A waiver is a judgment call the-Evidence Bundle must show, never a silent pass. Use the `CLAUDE.md` section map-to decide: `agents`/`lifecycle` cover `SPECIALIST_REGISTRY` and committee-semantics, `caching` covers any `cache_control` or `executive_persona` change,-`schemas` covers any `CREATE TABLE` in a `*/store.py` or `*/persistence.py`,-`api` covers any response-shape change under `api/`.--When you edit a prebuilt JSON, validate it with-`python3 -m json.tool packages/core/openexecutive/architecture/prebuilt/<id>.json > /dev/null`-(always pass the file path — with no argument `json.tool` reads stdin and-hangs) and keep the section heading out of `markdown` — the UI renders the-title.--### Prompt-caching invariant (`check_name='caching-invariant'`)--Breaking prompt caching = ~10x cost. Run this check in 5b when the staged diff-touches `prompts/cache_manager.py`, `prompts/executive_persona.py`,-`memory/company_profile.py`, or any line containing `cache_control`. Flag (FAIL):--- dynamic content (f-strings, `.format()`, `+`-concatenation, interpolation)- inside a system block that carries `cache_control`,-- `executive_persona` being f-stringed or concatenated — it must be passed as a- constant (`CLAUDE.md`: "NEVER f-stringed"),-- tool definitions not sorted by name in the cached tools block,-- RAG / per-request context placed in a system block instead of the user turn.--```bash-git --no-pager diff --staged -- packages/core/openexecutive/prompts/cache_manager.py \- packages/core/openexecutive/prompts/executive_persona.py | \- grep -nE "f\"|f'|\.format\(|cache_control" || true-```--A hit is a prompt to inspect, not an automatic fail — confirm the dynamic value-is not inside a cached block before passing. When any of these files are in the-diff, also append a caching-invariant clause to the reviewer prompt in 5c (all-three anvil reviewer agents are primed for it — security and quality check the-cached-block hygiene, logic checks tool ordering and the async/Pydantic-invariants from `CLAUDE.md`).--### PR requirements (`CLAUDE.md` → `## PR Requirements`)--Run these in 5b and INSERT each:--- **No stubs** (`check_name='no-stubs'`, FAIL on hit): added lines must not- introduce stubs.- ```bash- git --no-pager diff --staged | grep -nE '^\+' | \- grep -E 'TODO|FIXME|raise NotImplementedError|pass\s+#\s*stub|\.\.\.\s*#\s*stub' || true- ```-- **Eval scenarios for new agents / prompt changes**- (`check_name='eval-scenarios'`, FAIL if missing): if the diff adds a file under- `packages/core/openexecutive/agents/` or modifies- `prompts/domain_prompts.py`, it must also add/modify a file under- `packages/core/openexecutive/evals/_scenarios/`. Reference the `CLAUDE.md` "Adding a New Specialist Agent"- checklist in the failure message.-- **Tests for new behavior** (`check_name='tests-present'`, WARN — Medium- confidence, not a hard block): if non-trivial logic changed under- `packages/core/openexecutive/` with no corresponding change under- `packages/core/tests/`, flag it. Don't fail pure refactors or doc/config-only- diffs.diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex 12c3a010..da808071 100644--- a/.github/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -7,6 +7,8 @@3. Copy `.env.example` to `.env` and add your `ANTHROPIC_API_KEY`4. Start the dev server: `make dev`5. Run the tests: `make test`+6. Before opening a PR: `make check` (lint, unit tests, the UI build if+ `packages/ui` changed, and the PR rules below)## Branch Naming@@ -19,7 +21,8 @@## PR RequirementsAll PRs must:-1. Pass CI (ruff, mypy, unit tests)+1. Pass CI (ruff, mypy, unit tests, and `scripts/pr_checks.py` — the no-stubs,+ eval-scenario and architecture-docs rules below)2. Include working code — no stubs, no placeholders3. Include tests for new behavior4. For new or modified agents: include at least 2 eval scenarios@@ -85,6 +88,21 @@ Each `prebuilt/<id>.json` carries `section_id`, `title`, `markdown`, `mermaid``python -m json.tool`. Pure additions to `SPECIALIST_REGISTRY` areauto-reflected in the `agents` facts and need no YAML edit.+CI enforces this with `scripts/pr_checks.py`: a change under a documented+module fails unless one of that module's `prebuilt/<section>.json` files also+changed (the module → section map is `SECTIONS_FOR` in that script; update it+when you add a module or section). A YAML-only edit does not count. If the+change genuinely does not alter what the section describes (a rename, an+internal refactor), waive it with a line in a commit message or the PR+description:++```+Arch-Docs: n/a - <reason>+```++The CI job reads the PR description when it runs, so after adding the line+to the description, push a commit or re-run the job.+## Prompt ChangesPrompt changes to `executive_persona.py` or `domain_prompts.py` require:diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 1a562865..c8436b17 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -39,6 +39,30 @@ jobs:- name: Run mypyrun: cd packages/core && uv run mypy openexecutive/ --ignore-missing-imports+ pr-checks:+ name: PR rules (arch docs, stubs, evals)+ if: github.event_name == 'pull_request'+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v7+ with:+ fetch-depth: 0+ persist-credentials: false++ - name: Set up Python+ uses: actions/setup-python@v7+ with:+ python-version: "3.11"++ # Rules from CLAUDE.md ("Architecture Docs", "PR Requirements"). The PR+ # body is read for an "Arch-Docs: n/a - <reason>" waiver; it goes in via+ # env, never interpolated into the script.+ - name: Check PR rules+ env:+ PR_BODY: ${{ github.event.pull_request.body }}+ BASE_REF: ${{ github.base_ref }}+ run: python scripts/pr_checks.py --base "origin/$BASE_REF"+python-test:name: Python testsruns-on: ubuntu-latestdiff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.ymlnew file mode 100644index 00000000..ca9bc35a--- /dev/null+++ b/.github/workflows/claude-code-review.yml@@ -0,0 +1,94 @@+name: Claude Code Review++# Reviews every non-draft PR with Claude (anthropics/claude-code-action) and+# posts findings as inline comments plus one summary comment.+#+# Setup (once, by a repo admin):+# 1. Install the Claude GitHub App on the repo:+# https://github.com/apps/claude+# 2. Add ONE repository secret (Settings -> Secrets and variables -> Actions):+# ANTHROPIC_API_KEY (API billing) or CLAUDE_CODE_OAUTH_TOKEN (a Claude+# subscription; create it with `claude setup-token`).+# Until a secret is set the job skips with a notice instead of failing.+#+# Fork PRs are skipped: GitHub does not pass secrets to them.++on:+ pull_request:+ types: [opened, synchronize, ready_for_review, reopened]++# A new push supersedes a review still running on the previous one.+concurrency:+ group: ${{ github.workflow }}-${{ github.event.pull_request.number }}+ cancel-in-progress: true++permissions:+ contents: read++jobs:+ review:+ if: >-+ github.event.pull_request.draft == false &&+ github.event.pull_request.head.repo.full_name == github.repository &&+ github.actor != 'dependabot[bot]'+ runs-on: ubuntu-latest+ permissions:+ contents: read+ pull-requests: write+ issues: read+ id-token: write+ steps:+ - name: Check for credentials+ id: auth+ env:+ HAS_KEY: ${{ secrets.ANTHROPIC_API_KEY != '' || secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }}+ run: |+ if [ "$HAS_KEY" = "true" ]; then+ echo "ready=true" >> "$GITHUB_OUTPUT"+ else+ echo "::notice::Claude review skipped: set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN (see the header of .github/workflows/claude-code-review.yml)."+ fi++ - uses: actions/checkout@v7+ if: steps.auth.outputs.ready == 'true'+ with:+ fetch-depth: 1++ - name: Review the PR+ if: steps.auth.outputs.ready == 'true'+ uses: anthropics/claude-code-action@v1+ with:+ anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}+ claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}+ prompt: |+ REPO: ${{ github.repository }}+ PR NUMBER: ${{ github.event.pull_request.number }}++ Review this pull request. Read CLAUDE.md first: it holds the+ project's invariants and PR rules. Read the diff with+ `gh pr diff`, and open the surrounding code when you need it.++ Report only real problems, most severe first:+ 1. Bugs: wrong logic, missing edge cases, broken error handling,+ races, a sync call where the code must be async.+ 2. Security: injection, auth bypass, secrets or company data in+ the diff, untrusted input reaching a dangerous sink, a+ removed or narrowed .gitignore rule.+ 3. CLAUDE.md invariants: dynamic content inside a cached system+ prompt block, the executive persona f-stringed, tools not+ sorted by name, RAG context in the system prompt instead of+ the user turn, `class Config` instead of `model_config`, a+ sync `anthropic.Anthropic()` client, a specialist missing+ from SPECIALIST_TOOLS or `_AREAS`.+ 4. Missing tests for new behavior.++ Skip style nits that ruff/mypy would catch and anything the+ `pr-checks` CI job already enforces (architecture-doc drift,+ stub markers, eval scenarios).++ Put each finding as an inline comment on the line it concerns,+ with a concrete failing input or scenario. Finish with one+ short PR comment summarizing the findings, or saying none were+ found. Do not approve or request changes.+ claude_args: |+ --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Read,Grep,Glob"diff --git a/CLAUDE.md b/CLAUDE.mdindex 21a15704..ee23c156 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -21,6 +21,7 @@ docker/ Dockerfile + docker-compose.ymlmake dev # Start FastAPI (port 8000) + Next.js (port 3000)make test # Run pytestmake lint # ruff check + mypy+make check # everything CI checks: lint, unit tests, UI build (if touched), PR rulesmake eval # Run eval suite against localhostmake docker # docker compose up --build```@@ -129,6 +130,8 @@ When your PR materially changes a documented topic, **re-author the affected `prEach `prebuilt/<id>.json` has the keys `section_id`, `title`, `markdown`, `mermaid` (a Mermaid string or `null`), and `generated_at`. The Markdown must not include the section heading (the UI renders the title). Validate edits with `python -m json.tool`.+CI enforces this with `scripts/pr_checks.py` (also run by `make check`): a change under a documented module fails unless one of that module's `prebuilt/<section>.json` files changed too. The module → section map is `SECTIONS_FOR` in that script; update it when you add a module or section. When a change genuinely does not alter what a section describes, waive it with a line `Arch-Docs: n/a - <reason>` in a commit message or the PR description.+## Local Hosts`make dev` serves both:@@ -217,7 +220,7 @@ make eval # runs packages/core/openexecutive/evals/_scenarios/*.yaml, writes e- No stubs — working code only- Tests for new behavior- Eval scenarios for new agents or prompt changes-- `ruff check` and `mypy` must pass+- `ruff check` and `mypy` must pass — `make check` runs these, the unit tests and `scripts/pr_checks.py` (no stubs, eval scenarios, arch-doc drift) the way CI does- Architecture docs updated per `## Architecture Docs` above (when integrations, scheduler, departments/people, caching, invariants, routing patterns, or top-level modules change)- PR title is `type(scope): what changed`, in the imperative — e.g.`fix(chat): bind the session for the whole SSE turn`. Types: `fix`, `feat`,@@ -253,9 +256,12 @@ make eval # runs packages/core/openexecutive/evals/_scenarios/*.yaml, writes efindings and alternatives go in the commit message; open questions go in thereview thread. Keep the body short enough to read in one screen.-## Workflow+## Definition of Done++Before calling a code change done or opening a PR:-- For any task that writes, modifies, refactors, fixes, or plans code changes- in this repo, invoke the `anvil` skill before editing. This applies to bug- fixes, new features, refactors, and config changes — including small edits.-- Research-only tasks (read, search, explain, summarize) do not require Anvil.+- `make check` passes. It unsets `BACKEND_SHARED_SECRET` / `OE_PUBLIC_DEPLOYMENT` for the tests, so the Testing gotchas above don't bite.+- New behavior has tests; a new agent or prompt change has eval scenarios.+- A change to what a documented topic describes updates its `prebuilt/<section>.json` (see Architecture Docs), or carries an `Arch-Docs: n/a - <reason>` waiver.+- A change touching `api/`, `integrations/`, `mcp_server/`, auth, `orchestrator/outbound_guard.py`, the cached prompt blocks or `.gitignore` gets a pass from the `security-reviewer` agent (or `/security-review`) before the PR opens.+- Every non-draft PR also gets an automated Claude review (`.github/workflows/claude-code-review.yml`) as inline comments. Fix or answer each finding.diff --git a/Makefile b/Makefileindex 5132547b..249681ef 100644--- a/Makefile+++ b/Makefile@@ -1,4 +1,4 @@-.PHONY: dev stop test lint eval docker clean install discord+.PHONY: dev stop test lint check eval docker clean install discordinstall:cd packages/core && uv sync@@ -52,6 +52,19 @@ test:lint:cd packages/core && uv run ruff check openexecutive/ && uv run mypy openexecutive/+# Everything CI checks, in one command. Unsets the two env vars that make+# full-app tests 401 or fail at import (see CLAUDE.md -> Testing), builds the+# UI only when packages/ui differs from BASE, then runs the PR rules.+BASE ?= origin/main+check: lint+ cd packages/core && env -u BACKEND_SHARED_SECRET -u OE_PUBLIC_DEPLOYMENT \+ uv run pytest tests/unit/ -n auto --dist loadfile -q+ @if ! git diff --quiet $$(git merge-base $(BASE) HEAD) -- packages/ui \+ || [ -n "$$(git ls-files --others --exclude-standard packages/ui)" ]; then \+ cd packages/ui && npm run build; \+ else echo "packages/ui unchanged - skipping UI build"; fi+ python3 scripts/pr_checks.py --base $(BASE)+eval:cd packages/core && uv run python ../../evals/run_evals.py \--scenarios openexecutive/evals/_scenarios/ \diff --git a/packages/core/tests/unit/test_pr_checks.py b/packages/core/tests/unit/test_pr_checks.pynew file mode 100644index 00000000..535e9c76--- /dev/null+++ b/packages/core/tests/unit/test_pr_checks.py@@ -0,0 +1,282 @@+"""Tests for scripts/pr_checks.py, the CI gate for the PR rules in CLAUDE.md."""++from __future__ import annotations++import importlib.util+import subprocess+import sys+from pathlib import Path++import pytest++_SCRIPT = Path(__file__).resolve().parents[4] / "scripts" / "pr_checks.py"+_spec = importlib.util.spec_from_file_location("pr_checks", _SCRIPT)+assert _spec and _spec.loader+pr_checks = importlib.util.module_from_spec(_spec)+sys.modules["pr_checks"] = pr_checks # dataclasses resolve annotations via sys.modules+_spec.loader.exec_module(pr_checks)++Change = pr_checks.Change+PKG = "packages/core/openexecutive/"+PREBUILT = PKG + "architecture/prebuilt/"+++def _level(check, **kw) -> str:+ kw.setdefault("changed", set())+ kw["changed"] = set(kw["changed"]) | set(kw.get("added", ()))+ return check(Change(**kw)).level+++# --- arch-doc-drift ----------------------------------------------------------+++def test_drift_fails_when_documented_module_changes_without_its_section() -> None:+ changed = {PKG + "integrations/slack.py", PREBUILT + "scheduler.json"}+ assert _level(pr_checks.check_arch_drift, changed=changed) == "FAIL"+++def test_drift_passes_when_matching_section_edited() -> None:+ changed = {PKG + "integrations/slack.py", PREBUILT + "integrations.json"}+ assert _level(pr_checks.check_arch_drift, changed=changed) == "PASS"+++def test_drift_accepts_any_of_several_sections() -> None:+ changed = {PKG + "orchestrator/executive.py", PREBUILT + "lifecycle.json"}+ assert _level(pr_checks.check_arch_drift, changed=changed) == "PASS"+++def test_drift_yaml_only_edit_does_not_count() -> None:+ changed = {PKG + "scheduler/jobs.py", PKG + "architecture/architecture-facts.yaml"}+ assert _level(pr_checks.check_arch_drift, changed=changed) == "FAIL"+++def test_drift_ignores_non_doc_modules_and_other_packages() -> None:+ changed = {+ PKG + "utils/text.py",+ PKG + "cli.py",+ PKG + "evals/runner.py",+ "packages/ui/src/app/page.tsx",+ "packages/core/tests/unit/test_x.py",+ }+ assert _level(pr_checks.check_arch_drift, changed=changed) == "PASS"+++def test_drift_unmapped_module_needs_some_section() -> None:+ assert _level(pr_checks.check_arch_drift, changed={PKG + "config.py"}) == "FAIL"+ changed = {PKG + "config.py", PREBUILT + "overview.json"}+ assert _level(pr_checks.check_arch_drift, changed=changed) == "PASS"+++def test_drift_new_module_needs_section_spec_page_and_json() -> None:+ added = {PKG + "billing/__init__.py", PKG + "billing/core.py"}+ result = pr_checks.check_arch_drift(Change(changed=set(added), added=added))+ assert result.level == "FAIL"+ assert "billing.json" in result.detail and "sections.py" in result.detail++ changed = added | {+ PREBUILT + "billing.json",+ PKG + "architecture/sections.py",+ "packages/ui/src/app/architecture/page.tsx",+ }+ assert _level(pr_checks.check_arch_drift, changed=changed, added=added) == "PASS"+++ "text",+ ["Arch-Docs: n/a - internal rename", "fix x\n\narch-docs: N/A — no behavior change"],+)+def test_drift_waiver_line_passes(text: str) -> None:+ changed = {PKG + "integrations/slack.py"}+ assert _level(pr_checks.check_arch_drift, changed=changed, waiver_text=text) == "PASS"+++ "text", ["we did not add Arch-Docs: n/a - here", "Arch-Docs: n/a", "Arch-Docs: na -"]+)+def test_drift_waiver_needs_own_line_and_reason(text: str) -> None:+ changed = {PKG + "integrations/slack.py"}+ assert _level(pr_checks.check_arch_drift, changed=changed, waiver_text=text) == "FAIL"+++# --- no-stubs ----------------------------------------------------------------+++ "line", [" # TODO: finish", " raise NotImplementedError", " pass # stub"]+)+def test_no_stubs_fails_on_stub_in_code(line: str) -> None:+ lines = {PKG + "memory/store.py": ["x = 1", line]}+ assert _level(pr_checks.check_no_stubs, added_lines=lines) == "FAIL"+++def test_no_stubs_ignores_docs_and_exempt_files() -> None:+ lines = {+ "docs/roadmap.md": ["- TODO: write this"],+ "scripts/pr_checks.py": ["STUB_RE = 'TODO'"],+ PKG + "memory/store.py": ["todos = load_todos()"],+ }+ assert _level(pr_checks.check_no_stubs, added_lines=lines) == "PASS"+++# --- eval-scenarios ----------------------------------------------------------+++def test_eval_scenarios_required_for_new_agent() -> None:+ added = {PKG + "agents/sales.py"}+ assert _level(pr_checks.check_eval_scenarios, added=added) == "FAIL"+ changed = {PKG + "evals/_scenarios/sales_001.yaml"}+ assert _level(pr_checks.check_eval_scenarios, changed=changed, added=added) == "PASS"+++def test_eval_scenarios_required_for_domain_prompt_change() -> None:+ changed = {PKG + "prompts/domain_prompts.py"}+ assert _level(pr_checks.check_eval_scenarios, changed=changed) == "FAIL"+++def test_eval_scenarios_not_required_for_editing_existing_agent() -> None:+ changed = {PKG + "agents/finance.py"}+ assert _level(pr_checks.check_eval_scenarios, changed=changed) == "PASS"+++def test_eval_scenarios_not_required_for_rename_or_private_module() -> None:+ renamed = {PKG + "agents/finance_agent.py"}+ assert _level(pr_checks.check_eval_scenarios, changed=renamed, renamed=renamed) == "PASS"+ added = {PKG + "agents/_helpers.py", PKG + "agents/__init__.py"}+ assert _level(pr_checks.check_eval_scenarios, added=added) == "PASS"+++def test_parse_added_lines_only_trusts_headers() -> None:+ diff = "\n".join(+ [+ "diff --git a/x.py b/x.py",+ "--- a/x.py",+ "+++ b/x.py",+ "@@ -1 +1,3 @@",+ "+++ a", # an added line that reads "++ a"+ "++++ b/other.py",+ "+y = 2 # TODO",+ 'diff --git "a/t\\tab.py" "b/t\\tab.py"',+ "--- /dev/null",+ '+++ "b/t\\tab.py"',+ "@@ -0,0 +1 @@",+ "+z = 1",+ "diff --git a/gone.py b/gone.py",+ "--- a/gone.py",+ "+++ /dev/null",+ "@@ -1 +0,0 @@",+ "-old",+ ]+ )+ assert pr_checks._parse_added_lines(diff) == {+ "x.py": ["++ a", "+++ b/other.py", "y = 2 # TODO"],+ "t\tab.py": ["z = 1"],+ }+++# --- tests-present -----------------------------------------------------------+++def test_tests_present_warns_only() -> None:+ changed = {PKG + "memory/store.py"}+ assert _level(pr_checks.check_tests_present, changed=changed) == "WARN"+ changed.add("packages/core/tests/unit/test_store.py")+ assert _level(pr_checks.check_tests_present, changed=changed) == "PASS"+++# --- git plumbing ------------------------------------------------------------+++def _git(repo: Path, *args: str) -> None:+ subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True)+++def test_collect_and_main_against_a_real_repo(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]+) -> None:+ repo = tmp_path+ _git(repo, "init", "-q", "-b", "main")+ _git(repo, "config", "user.email", "[email protected]")+ _git(repo, "config", "user.name", "t")+ slack = repo / PKG / "integrations" / "slack.py"+ slack.parent.mkdir(parents=True)+ slack.write_text("x = 1\n")+ _git(repo, "add", "-A")+ _git(repo, "commit", "-qm", "base")+ _git(repo, "checkout", "-qb", "feature")++ slack.write_text("x = 1\ny = 2 # TODO\n") # uncommitted edit+ new = repo / PKG / "agents" / "sales.py"+ new.parent.mkdir(parents=True)+ new.write_text("z = 3\n") # untracked file+ monkeypatch.chdir(repo)+ monkeypatch.delenv("PR_BODY", raising=False)++ change = pr_checks.collect("main")+ assert PKG + "integrations/slack.py" in change.changed+ assert PKG + "agents/sales.py" in change.added+ assert change.added_lines[PKG + "integrations/slack.py"] == ["y = 2 # TODO"]++ assert pr_checks.main(["--base", "main"]) == 1+ out = capsys.readouterr().out+ assert "FAIL arch-doc-drift" in out and "FAIL no-stubs" in out++ slack.write_text("x = 1\ny = 2\n")+ _git(repo, "add", "-A")+ _git(repo, "commit", "-qm", "add sales\n\nArch-Docs: n/a - test fixture")+ monkeypatch.setenv("PR_BODY", "")+ assert pr_checks.main(["--base", "main"]) == 1 # eval scenarios still missing+ out = capsys.readouterr().out+ assert "waived (Arch-Docs: n/a - test fixture)" in out and "FAIL eval-scenarios" in out++ monkeypatch.setenv("PR_BODY", "## Problem\n\nArch-Docs: n/a - from the PR body\n")+ _git(repo, "commit", "-q", "--amend", "-m", "add sales")+ pr_checks.main(["--base", "main"])+ assert "waived (Arch-Docs: n/a - from the PR body)" in capsys.readouterr().out+++def test_collect_survives_odd_files_and_git_config(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ repo = tmp_path+ _git(repo, "init", "-q", "-b", "main")+ _git(repo, "config", "user.email", "[email protected]")+ _git(repo, "config", "user.name", "t")+ _git(repo, "config", "diff.noprefix", "true")+ _git(repo, "config", "diff.renames", "false")+ old = repo / PKG / "memory" / "old name.py"+ old.parent.mkdir(parents=True)+ old.write_text("# TODO carried over\n" * 5)+ _git(repo, "add", "-A")+ _git(repo, "commit", "-q", "-m", "base")+ _git(repo, "checkout", "-qb", "feature")+ _git(repo, "mv", str(old), str(old.with_name("new name.py")))+ integ = repo / PKG / "integrations"+ integ.mkdir(parents=True)+ (integ / "caf\u00e9.py").write_text("# TODO\n")+ (integ / "latin1.txt").write_bytes(b"caf\xe9\n")+ (integ / "sp ace.py").write_text("raise NotImplementedError\n")+ _git(repo, "add", "-A")+ _git(repo, "commit", "-qm", "odd files")+ monkeypatch.chdir(repo)++ change = pr_checks.collect("main")+ assert PKG + "integrations/caf\u00e9.py" in change.added+ assert change.added_lines[PKG + "integrations/caf\u00e9.py"] == ["# TODO"]+ assert change.added_lines[PKG + "integrations/sp ace.py"] == ["raise NotImplementedError"]+ assert PKG + "integrations/latin1.txt" in change.changed+ assert {PKG + "memory/old name.py", PKG + "memory/new name.py"} <= change.changed+ assert change.renamed == {PKG + "memory/new name.py"}+ assert PKG + "memory/new name.py" not in change.added_lines # a pure move adds no lines+ assert pr_checks.check_no_stubs(change).level == "FAIL"+ assert pr_checks.check_arch_drift(change).level == "FAIL"+++def test_main_reports_missing_base(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]+) -> None:+ _git(tmp_path, "init", "-q", "-b", "main")+ _git(tmp_path, "-c", "[email protected]", "-c", "user.name=t", "commit", "-q",+ "--allow-empty", "-m", "base")+ monkeypatch.chdir(tmp_path)+ assert pr_checks.main(["--base", "origin/nope"]) == 2+ assert "is 'origin/nope' fetched?" in capsys.readouterr().outdiff --git a/scripts/pr_checks.py b/scripts/pr_checks.pynew file mode 100644index 00000000..f15491a5--- /dev/null+++ b/scripts/pr_checks.py@@ -0,0 +1,319 @@+#!/usr/bin/env python3+"""Repo rules a PR must meet, checked against the diff from a base ref.++Runs in CI on every pull request and locally via `make check`:++ python3 scripts/pr_checks.py # diff vs origin/main+ python3 scripts/pr_checks.py --base origin/x++Checks (see CLAUDE.md -> "Architecture Docs" and "PR Requirements"):++- arch-doc-drift FAIL a documented module changed but its+ architecture/prebuilt/<section>.json did not+- no-stubs FAIL added code lines carry TODO/FIXME/NotImplementedError+- eval-scenarios FAIL a new agent or a domain-prompt change without an+ evals/_scenarios/ change+- tests-present WARN openexecutive/ code changed with no tests/ change++A change that does not alter what a section describes can waive the drift+check with a line in a commit message or the PR description:++ Arch-Docs: n/a - <reason>++Stdlib only, so it runs without the project's virtualenv.+"""++from __future__ import annotations++import argparse+import codecs+import os+import re+import subprocess+import sys+from collections.abc import Iterable+from dataclasses import dataclass, field++PKG = "packages/core/openexecutive/"+PREBUILT = PKG + "architecture/prebuilt/"+SECTIONS_PY = PKG + "architecture/sections.py"+ARCH_PAGE = "packages/ui/src/app/architecture/page.tsx"+TESTS = "packages/core/tests/"+SCENARIOS = PKG + "evals/_scenarios/"+AGENTS = PKG + "agents/"+DOMAIN_PROMPTS = PKG + "prompts/domain_prompts.py"++# Modules with no /architecture section.+NON_DOC = {"architecture", "utils", "cli", "evals", "__init__"}++# Module -> the section ids documenting it; editing any one satisfies the gate.+# A module missing here accepts an edit to any section. Keep in step with+# architecture/sections.py and the topic map in CLAUDE.md.+SECTIONS_FOR: dict[str, set[str]] = {+ "integrations": {"integrations"},+ "scheduler": {"scheduler"},+ "workflows": {"workflows"},+ "prompts": {"caching"},+ "departments": {"org"},+ "people": {"org"},+ "personas": {"org"},+ "onboarding": {"org"},+ "memory": {"memory", "peer_memory"},+ "api": {"api", "today"},+ "orchestrator": {"agents", "lifecycle", "review"},+ "agents": {"agents", "lifecycle", "review"},+ "providers": {"agents", "lifecycle", "review"},+ "audit": {"audit"},+ "attunement": {"attunement"},+ "monitoring": {"external_monitoring"},+ "mcp_server": {"mcp_server"},+ "clients": {"clients", "peer_memory"},+ "fixtures": {"clients", "peer_memory"},+ "knowledge": {"rag"},+ "briefing": {"today"},+ "alerts": {"today"},+ "guide": {"user_guide"},+}++# Needs a reason after the n/a: "Arch-Docs: n/a - renamed a helper".+WAIVER_RE = re.compile(+ r"^[ \t]*Arch-Docs:[ \t]*n/?a\b[ \t]*[-\u2013\u2014:][ \t]*\S.*$",+ re.IGNORECASE | re.MULTILINE,+)+STUB_RE = re.compile(+ r"\bTODO\b|\bFIXME\b|raise NotImplementedError|pass\s+#\s*stub|\.\.\.\s*#\s*stub"+)+CODE_EXT = (".py", ".ts", ".tsx", ".js", ".jsx")+# These files name the stub patterns themselves.+STUB_EXEMPT = {"scripts/pr_checks.py", TESTS + "unit/test_pr_checks.py"}+++@dataclass+class Change:+ """The part of a diff the checks look at."""++ changed: set[str]+ added: set[str] = field(default_factory=set)+ # new paths of moved files: new to a module, but not new code+ renamed: set[str] = field(default_factory=set)+ # path -> lines the diff adds to that file+ added_lines: dict[str, list[str]] = field(default_factory=dict)+ waiver_text: str = ""+++@dataclass+class Result:+ name: str+ level: str # PASS | WARN | FAIL+ detail: str+++def _module_of(path: str) -> str | None:+ if not path.startswith(PKG):+ return None+ head = path[len(PKG) :].split("/", 1)+ if len(head) == 1:+ return head[0][:-3] if head[0].endswith(".py") else None+ return head[0]+++def check_arch_drift(c: Change) -> Result:+ name = "arch-doc-drift"+ touched = {+ p[len(PREBUILT) : -len(".json")]+ for p in c.changed+ if p.startswith(PREBUILT) and p.endswith(".json") and "/" not in p[len(PREBUILT) :]+ }+ modules = sorted({m for p in c.changed if (m := _module_of(p)) and m not in NON_DOC})+ if not modules:+ return Result(name, "PASS", "no documented module changed")+ new_modules = {+ m+ for p in c.added | c.renamed+ if p.startswith(PKG) and p.endswith("/__init__.py") and p.count("/") == 4+ for m in [_module_of(p)]+ if m and m not in NON_DOC+ }++ missing: list[str] = []+ for m in modules:+ if m in new_modules:+ needs = [f"prebuilt/{m}.json"] if m not in touched else []+ needs += [p.rsplit("/", 1)[-1] for p in (SECTIONS_PY, ARCH_PAGE) if p not in c.changed]+ if needs:+ missing.append(f"{m} (new module, also needs: {', '.join(needs)})")+ continue+ expect = SECTIONS_FOR.get(m)+ if expect is None:+ if not touched:+ missing.append(f"{m} (no section edited)")+ elif not expect & touched:+ missing.append(f"{m} (edit one of: {', '.join(sorted(expect))})")++ if not missing:+ return Result(name, "PASS", f"modules={modules} sections={sorted(touched)}")+ if waived := WAIVER_RE.search(c.waiver_text):+ waiver = waived.group(0).strip()+ return Result(name, "PASS", f"waived ({waiver}); would need: {'; '.join(missing)}")+ return Result(+ name,+ "FAIL",+ "architecture docs not updated for: "+ + "; ".join(missing)+ + f". Edit {PREBUILT}<section>.json (and architecture-facts.yaml), or add "+ "'Arch-Docs: n/a - <reason>' to a commit message or the PR description.",+ )+++def check_no_stubs(c: Change) -> Result:+ hits = [+ f"{path}: {line.strip()[:80]}"+ for path, lines in sorted(c.added_lines.items())+ if path.endswith(CODE_EXT) and path not in STUB_EXEMPT+ for line in lines+ if STUB_RE.search(line)+ ]+ if hits:+ return Result("no-stubs", "FAIL", "stub markers in added lines: " + " | ".join(hits[:5]))+ return Result("no-stubs", "PASS", "no stub markers added")+++def check_eval_scenarios(c: Change) -> Result:+ new_agent = any(+ p.startswith(AGENTS) and p.endswith(".py") and not p.rsplit("/", 1)[-1].startswith("_")+ for p in c.added+ )+ prompt_change = DOMAIN_PROMPTS in c.changed+ if not (new_agent or prompt_change):+ return Result("eval-scenarios", "PASS", "no new agent or domain-prompt change")+ if any(p.startswith(SCENARIOS) for p in c.changed):+ return Result("eval-scenarios", "PASS", "eval scenarios updated")+ why = "new specialist agent" if new_agent else "domain_prompts.py changed"+ return Result(+ "eval-scenarios",+ "FAIL",+ f"{why} but nothing under {SCENARIOS} changed "+ "(see CLAUDE.md -> 'Adding a New Specialist Agent').",+ )+++def check_tests_present(c: Change) -> Result:+ code = [+ p+ for p in c.changed+ if p.startswith(PKG) and p.endswith(".py") and _module_of(p) not in NON_DOC+ ]+ if not code or any(p.startswith(TESTS) for p in c.changed):+ return Result("tests-present", "PASS", "tests changed or no code changed")+ return Result(+ "tests-present",+ "WARN",+ f"{len(code)} openexecutive/ file(s) changed with no change under {TESTS} "+ "- fine for a pure refactor, otherwise add tests.",+ )+++CHECKS = (check_arch_drift, check_no_stubs, check_eval_scenarios, check_tests_present)+++def run_checks(c: Change) -> list[Result]:+ return [check(c) for check in CHECKS]+++# --- git plumbing -----------------------------------------------------------+++def _git(*args: str) -> str:+ # Pin the output format against user config (quotePath, noprefix, renames,+ # external diff tools), and never crash on a non-UTF-8 file.+ cmd = ["git", "-c", "core.quotePath=false", *args]+ return subprocess.run(+ cmd, check=True, capture_output=True, encoding="utf-8", errors="replace"+ ).stdout+++def _unquote(path: str) -> str:+ """Undo git's C-style quoting of a path with a tab, quote or backslash."""+ if not (path.startswith('"') and path.endswith('"')):+ return path+ raw = codecs.escape_decode(path[1:-1].encode("utf-8"))[0]+ return raw.decode("utf-8", errors="replace")+++def _parse_added_lines(diff: str) -> dict[str, list[str]]:+ out: dict[str, list[str]] = {}+ current: str | None = None+ in_header = False+ for line in diff.splitlines():+ if line.startswith("diff --git "):+ in_header, current = True, None+ elif in_header and line.startswith("+++ "):+ # git ends a path containing a space with a tab+ target = _unquote(line[4:].rstrip("\t"))+ current = target[2:] if target.startswith("b/") else None+ elif line.startswith("@@"):+ in_header = False+ elif current and not in_header and line.startswith("+"):+ out.setdefault(current, []).append(line[1:])+ return out+++def collect(base: str, extra_waiver: Iterable[str] = ()) -> Change:+ """Diff the working tree (committed + uncommitted + untracked) against base."""+ merge_base = _git("merge-base", base, "HEAD").strip()+ changed: set[str] = set()+ added: set[str] = set()+ renamed: set[str] = set()+ fields = _git("diff", "-z", "--name-status", "-M", merge_base).split("\0")+ i = 0+ while i < len(fields) - 1:+ status = fields[i]+ n = 2 if status[:1] in ("R", "C") else 1+ paths = fields[i + 1 : i + 1 + n]+ i += 1 + n+ changed.update(paths)+ if status.startswith("A"):+ added.add(paths[-1])+ elif status.startswith(("R", "C")):+ renamed.add(paths[-1])+ diff = _git(+ "diff", "-U0", "-M", "--no-color", "--no-ext-diff",+ "--src-prefix=a/", "--dst-prefix=b/", merge_base,+ )+ added_lines = _parse_added_lines(diff)++ for path in _git("ls-files", "-z", "--others", "--exclude-standard").split("\0"):+ if not path:+ continue+ changed.add(path)+ added.add(path)+ try:+ with open(path, encoding="utf-8", errors="replace") as fh:+ added_lines[path] = fh.read().splitlines()+ except OSError:+ pass++ waiver = _git("log", "--format=%B", f"{merge_base}..HEAD")+ return Change(changed, added, renamed, added_lines, "\n".join([waiver, *extra_waiver]))+++def main(argv: list[str] | None = None) -> int:+ ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])+ ap.add_argument("--base", default="origin/main", help="ref to diff against")+ args = ap.parse_args(argv)++ try:+ change = collect(args.base, [os.environ.get("PR_BODY", "")])+ except subprocess.CalledProcessError as exc:+ print(f"pr_checks: git {' '.join(exc.cmd[1:])} failed: {exc.stderr.strip()}")+ print(f"pr_checks: is '{args.base}' fetched? try `git fetch origin main`")+ return 2++ results = run_checks(change)+ for r in results:+ print(f"{r.level:<4} {r.name:<15} {r.detail}")+ return 1 if any(r.level == "FAIL" for r in results) else 0+++if __name__ == "__main__":+ sys.exit(main())