From 2c40b973fa03fd6188af013da5a528771c496213 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 05:09:21 +0000 Subject: [PATCH 1/3] Add CLAUDE.md with architecture guide and dev commands https://claude.ai/code/session_01PJCxiyuxxA5oLGDBBWsEkX --- CLAUDE.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..b65e239e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,120 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Commands + +```bash +# Development (starts all 3 processes: Vite :5001, Express :5000, Python :8001) +scripts/start-dev.sh + +# Production build (Vite → dist/public/, esbuild → dist/index.cjs) +npm run build + +# TypeScript type checking +npm run check + +# Push Drizzle schema to PostgreSQL +npm run db:push + +# Re-stamp all files with N:M ratio annotation (required after edits) +python scripts/annotate.py +``` + +### Tests + +```bash +# Install Playwright browser (first time) +npx playwright install chromium + +# Run all e2e tests (requires dev server on :5000) +npx playwright test + +# Run a single test file +npx playwright test tests/e2e/console-tabs.spec.ts + +# Console-tab regression guard (static preflight, no browser needed) +node scripts/check-console-tabs.mjs +``` + +## Architecture + +This is a 3-process autonomous AI agent platform with a metadata-driven console UI. + +### Process Topology + +``` +Browser → Express (:5000) → [proxy /api/*] → Python/FastAPI (:8001, internal only) + ↘ [dev] Vite (:5001) +``` + +- **Express** (`server/`) — Auth, sessions, guest-chat rate limiting, static serving. Adds `x-a0p-internal: ` and user identity headers (`x-user-id`, `x-user-email`, `x-user-role`) to every proxied request. Never expose Python port directly. +- **Python/FastAPI** (`python/`) — All AI orchestration, PCNA engine, agent lifecycle, billing, heartbeat scheduler. Validates `x-a0p-internal` on every request. +- **Vite** — Dev only; proxied by Express. + +### Frontend (Metadata-Driven Console) + +`client/src/hooks/use-ui-structure.ts` polls `GET /api/v1/ui/structure`, which aggregates `UI_META` from every Python route module. The console (`client/src/pages/console.tsx`) renders tabs from this structure: + +- Tabs listed in `CUSTOM_TAB_RENDERERS` → custom React component +- All other tabs → generic `TabRenderer` (schema-driven via `DATA_SCHEMA`) + +The **console-tab regression guard** (`scripts/check-console-tabs.mjs`) and e2e test (`tests/e2e/console-tabs.spec.ts`) enforce that every API-declared tab has either a custom renderer or sections. CI blocks deploy on failure. + +### Python Route Modules + +Each route file in `python/routes/` is self-declaring: it exports a FastAPI `router` and defines `UI_META`/`DATA_SCHEMA` at the top. **Adding a new route requires 4 edits to `python/routes/__init__.py`**: +1. Import the router +2. Add to `ALL_ROUTERS` +3. Add filename to `collect_doc_meta()` file list +4. Add module name to `collect_ui_meta()` module list + +File naming convention: `{name}.py` = self-contained module; `{name}_api.py` = thin delegate to a service in `python/services/`. + +### Key Python Services + +- `python/services/inference.py` — Orchestrates LLM calls (Grok-3 Mini default, Claude, Gemini); injects tier-specific `prompt_context` +- `python/services/heartbeat.py` — 30-second tick: audit snapshots, memory checkpoints, PCNA propagation, sub-agent cleanup +- `python/services/tool_executor.py` — Tool invocation with approval gates +- `python/pcna.py` / `python/engine.py` — 53-node PCNA ring engine (7 phases, core agent coherence system) +- `python/services/edcm.py` — Behavioral directive scoring (CM, DA, DRIFT, DVG, INT, TBF) that guides LLM selection + +### Database + +Schema source of truth is `shared/schema.ts` (Drizzle ORM); applied via `npm run db:push`. Python accesses the same PostgreSQL database via SQLAlchemy async (`python/database.py`, `python/models.py`). + +### Auth & Tiers + +Auth is handled entirely by Express. Tiers (Free → Seeker → Operator → Patron → Founder Lifetime) are stored on the user record, updated via Stripe webhook (`python/routes/billing.py`), and injected into the LLM system prompt as `prompt_context`. + +## Conventions + +- **File annotation** — Every file opens/closes with `// N:M` or `# N:M` (code:comment ratio). Run `python scripts/annotate.py` after edits. +- **Python route DOC blocks** — Each route file includes `# DOC module:`, `# DOC label:`, `# DOC description:`, `# DOC tier:`, `# DOC endpoint:` headers. +- **No file over 400 lines** — Annotation warns; split before it triggers CI. +- **All frontend `/api/*` calls go through Express on :5000** — never call Python :8001 directly. +- **Dynamic SQL UPDATE** — Use the column allowlist pattern already established in the codebase. + +## Key Files + +- `replit.md` — Platform overview and user preferences +- `DEPLOYMENT.md` — GCP/Cloud Run setup and secrets +- `spec.md` — Full agent platform spec (PCNA, EDCM, sentinel channels) +- `.agents/skills/a0p-module-doctrine/SKILL.md` — Authoritative module conventions +- `python/routes/__init__.py` — Module registration (edit when adding routes) +- `client/src/pages/console.tsx` — `CUSTOM_TAB_RENDERERS` map and tab rendering logic +- `.github/workflows/deploy.yml` — CI pipeline (regression guard → deploy) + +## Environment Variables + +Required in production (dev has safe fallbacks except where noted): + +```bash +SESSION_SECRET # Express session encryption (no fallback in prod) +INTERNAL_API_SECRET # Express→Python shared secret (random per-process in dev — use start-dev.sh) +DATABASE_URL # PostgreSQL connection string +XAI_API_KEY # Grok-3 Mini (primary LLM) +STRIPE_SECRET_KEY # Stripe billing +STRIPE_WEBHOOK_SECRET # Stripe webhook validation +ADMIN_USER_ID # User ID allowed to write prompt contexts +``` From 6d7968bca852329994e23a4092c70664f000a5c2 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 05:30:47 +0000 Subject: [PATCH 2/3] Fix PCNA engine path and description in CLAUDE.md python/pcna.py and python/engine.py don't exist; the engine lives at python/engine/pcna.py. Also corrects "7 phases" to the actual six-ring, six-step pipeline (Phi/Psi/Omega/Guardian/Memory-L/Memory-S). https://claude.ai/code/session_01PJCxiyuxxA5oLGDBBWsEkX --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index b65e239e..4d6ef375 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -76,7 +76,7 @@ File naming convention: `{name}.py` = self-contained module; `{name}_api.py` = t - `python/services/inference.py` — Orchestrates LLM calls (Grok-3 Mini default, Claude, Gemini); injects tier-specific `prompt_context` - `python/services/heartbeat.py` — 30-second tick: audit snapshots, memory checkpoints, PCNA propagation, sub-agent cleanup - `python/services/tool_executor.py` — Tool invocation with approval gates -- `python/pcna.py` / `python/engine.py` — 53-node PCNA ring engine (7 phases, core agent coherence system) +- `python/engine/pcna.py` — Six-ring PCNA inference pipeline (Phi/Psi/Omega/Guardian/Memory-L/Memory-S); six steps: Project → Inject → Propagate → PTCA-seed → PTCA-circle → Coherence - `python/services/edcm.py` — Behavioral directive scoring (CM, DA, DRIFT, DVG, INT, TBF) that guides LLM selection ### Database From 24f7a9d55926858b4676a05b70c65fd91a47ad69 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 05:41:17 +0000 Subject: [PATCH 3/3] Fix CLAUDE.md inaccuracies found by cross-checking sibling repos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - inference.py: remove "Grok-3 Mini default" — provider is configurable via energy_registry; actual grok model is grok-4-fast-reasoning, not grok-3-mini - edcm.py: remove "guides LLM selection" — EDCM fires behavioral directives (coherence_lock, drift_correction, etc.), not LLM routing - Add SigmaCore to key services — filesystem prime-ring tensor, custom console tab, companion to the Psi ring; was entirely absent - Update XAI_API_KEY comment to reflect actual model (Grok 4 Fast) https://claude.ai/code/session_01PJCxiyuxxA5oLGDBBWsEkX --- CLAUDE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4d6ef375..cfd11235 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -73,11 +73,12 @@ File naming convention: `{name}.py` = self-contained module; `{name}_api.py` = t ### Key Python Services -- `python/services/inference.py` — Orchestrates LLM calls (Grok-3 Mini default, Claude, Gemini); injects tier-specific `prompt_context` +- `python/services/inference.py` — Orchestrates LLM calls across registered energy providers; injects tier-specific `prompt_context` - `python/services/heartbeat.py` — 30-second tick: audit snapshots, memory checkpoints, PCNA propagation, sub-agent cleanup - `python/services/tool_executor.py` — Tool invocation with approval gates - `python/engine/pcna.py` — Six-ring PCNA inference pipeline (Phi/Psi/Omega/Guardian/Memory-L/Memory-S); six steps: Project → Inject → Propagate → PTCA-seed → PTCA-circle → Coherence -- `python/services/edcm.py` — Behavioral directive scoring (CM, DA, DRIFT, DVG, INT, TBF) that guides LLM selection +- `python/services/edcm.py` — Behavioral directive scoring (CM, DA, DRIFT, DVG, INT, TBF); fires corrective actions (coherence_lock, drift_correction, divergence_dampen, etc.) +- `python/engine/sigma.py` — SigmaCore: encodes the workspace filesystem as a prime-ring tensor; companion to the Psi ring; has its own console tab (`SigmaTab`) ### Database @@ -113,7 +114,7 @@ Required in production (dev has safe fallbacks except where noted): SESSION_SECRET # Express session encryption (no fallback in prod) INTERNAL_API_SECRET # Express→Python shared secret (random per-process in dev — use start-dev.sh) DATABASE_URL # PostgreSQL connection string -XAI_API_KEY # Grok-3 Mini (primary LLM) +XAI_API_KEY # Grok 4 Fast (reasoning) — one of the registered energy providers STRIPE_SECRET_KEY # Stripe billing STRIPE_WEBHOOK_SECRET # Stripe webhook validation ADMIN_USER_ID # User ID allowed to write prompt contexts