Merge pull request #450 from jmbish04/codex/open-pr-all-changes-20260331

Author: jmbish04

.agent/rules/000-bootstrap.md

@@ -2,14 +2,20 @@
 trigger: always_on
 ---
 
-# 000: BOOTSTRAP & PROTOCOL CHECK
-**CRITICAL: Mandatory Pre-flight Check.**
+# 000-bootstrap.md: Agent Genesis Directive
 
-Before starting any task, you must verify the following from `AGENTS.md`:
+## Core Operating Procedure
+1. **Initialize Context:** On the first turn of every session, read only `AGENTS.md` at the repo root to understand the system architecture and active specialist agents.
+2. **Standardization Protocol:** All implementation must align with the `StandardizationAgent` logic defined in `src/ai/agents/StandardizationAgent.ts`.
+3. **Lazy Load Rules:** Do NOT read all files in `.agent/rules/` by default. Instead, identify the relevant rules based on the task (e.g., read `ai-provider-standards.md` only for AI-related tasks).
 
-1.  **Workspace Context**: Identify if you are working in `frontend` or `container`. 
-2.  **Installation Protocol**: You MUST use `pnpm add <pkg> --filter <package>` from the root. Never install at root without `-w`.
-3.  **SDK Enforcement**: Verify you are using `@google/genai` (New SDK) and NOT `@google/generative-ai` (Legacy).
-4.  **Backend/Frontend Sync**: If modifying Drizzle schemas, ensure `frontend/src/db` is the target as per the "Schema Sync" section.
+## Environment Constraints
+- **Primary IDE:** Google Antigravity.
+- **Runtime:** Cloudflare Workers (workerd).
+- **Stack:** Hono (API), Astro 6 (Frontend), Drizzle ORM (D1 Data Layer).
+- **Architecture:** Unified Worker Assets with Cloudflare AI Gateway routing.
 
-**STOP**: If you have not explicitly read `AGENTS.md` in this session, do so now.
+## Code Output Rules
+- ALWAYS respond with full end-to-end code for the modified module.
+- NEVER use shortcuts or "rest of code" comments.
+- Ensure `integer('id').primaryKey({ autoIncrement: true })` is used for all Drizzle primary keys (D1/SQLite standard).

.agent/rules/000-core-directive.md

@@ -0,0 +1,135 @@
+# Rule: Dual-Scope Routing Paradigm
+
+## Overview
+
+This application enforces a strict **Dual-Scope Paradigm** for all views and API calls.
+Every new route, component, and API endpoint must declare which scope it belongs to.
+
+---
+
+## Scope Definitions
+
+### 🌐 Global Scope
+- **URL prefix:** `/` (no `/repos/:owner/:repo` prefix)
+- **Purview:** cross-repository; holistic planning; master dashboards; settings
+- **Route file:** `src/frontend/src/routes/GlobalRoutes.tsx`
+- **API pattern:** `/api/projects`, `/api/global/*`, `/api/tasks`, `/api/settings`
+- **Examples:** `/projects`, `/kanban`, `/roadmap`, `/dashboard`, `/chat`, `/workshop`
+
+### 🗂️ Active Workspace (Repo-Specific) Scope
+- **URL prefix:** `/repos/:owner/:repo/...`
+- **Purview:** strictly confined to a single selected GitHub `owner/repo`
+- **Route file:** `src/frontend/src/routes/RepoRoutes.tsx`
+- **API pattern:** `/api/repos/:owner/:repo/*`
+- **Examples:** `/repos/jmbish04/core-github-api/plan`, `.../prs`, `.../explorer`
+
+---
+
+## Rule 1 — Scope Declaration Before Implementation
+
+**When adding any new view, you MUST first determine its scope:**
+
+```
+Is this view useful regardless of which repo is selected?
+  → YES → Global Scope → add to GlobalRoutes.tsx
+  → NO  → Repo Scope  → add to RepoRoutes.tsx
+```
+
+Never add a route without explicitly declaring its scope in a comment:
+```tsx
+// SCOPE: GLOBAL — shows PRs across all watched repos
+<Route path="/pr-center" element={<PRCommandCenter />} />
+
+// SCOPE: REPO — shows PRs only for the active owner/repo workspace
+<Route path="prs" element={<RepoPRs />} />
+```
+
+---
+
+## Rule 2 — React Router v6 Relative Paths (MANDATORY)
+
+**Never repeat the parent path in a nested child route.**
+
+```tsx
+// ❌ WRONG — resolves to /repos/:owner/:repo/repos/:owner/:repo/plan
+<Route path="/repos/:owner/:repo" element={<RepoLayout />}>
+  <Route path="repos/:owner/:repo/plan" element={<RepoPlan />} />
+</Route>
+
+// ✅ CORRECT — resolves to /repos/:owner/:repo/plan
+<Route path="/repos/:owner/:repo" element={<RepoLayout />}>
+  <Route path="plan" element={<RepoPlan />} />
+</Route>
+```
+
+**Checklist for every child route inside `RepoRoutes.tsx`:**
+- [ ] Path does NOT start with `/`
+- [ ] Path does NOT contain `repos/:owner/:repo`
+- [ ] Path is a relative segment only (e.g., `"plan"`, `"projects/kanban"`)
+
+---
+
+## Rule 3 — Hono API Scope Validation
+
+All Hono router definitions must enforce scope validation with Zod.
+
+### Global API endpoints
+```typescript
+// src/backend/src/routes/api/global/projects.ts
+app.get("/api/projects", zValidator("query", GlobalProjectQuerySchema), handler);
+```
+
+### Repo-scoped API endpoints
+Every repo-scoped route must validate `owner` and `repo` using a shared Zod schema:
+
+```typescript
+// src/backend/src/routes/api/repos/[owner]/[repo]/projects.ts
+const RepoParamsSchema = z.object({
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+});
+
+app.get("/api/repos/:owner/:repo/projects",
+  zValidator("param", RepoParamsSchema),
+  async (c) => { /* ... */ }
+);
+```
+
+**Never** serve repo-scoped data from a global endpoint.
+**Never** call a global endpoint from a component inside `RepoRoutes.tsx`.
+
+---
+
+## Rule 4 — File Placement
+
+| Artifact | Global scope | Repo scope |
+|---|---|---|
+| Route definition | `src/frontend/src/routes/GlobalRoutes.tsx` | `src/frontend/src/routes/RepoRoutes.tsx` |
+| View component | `src/frontend/src/views/control/global/` | `src/frontend/src/views/repos/` |
+| Hono API handler | `src/backend/src/routes/api/...` | `src/backend/src/routes/api/repos/...` |
+| TanStack Query hook | uses `/api/*` | uses `/api/repos/:owner/:repo/*` |
+| Context dependency | no repo context needed | must consume `useRepoContext()` |
+
+---
+
+## Rule 5 — App.tsx Is a Composition Layer Only
+
+`App.tsx` must remain a thin provider + route composition layer.
+It imports `GlobalRoutes` and `RepoRoutes` and renders them inside `<Routes>`.
+**No route definitions belong directly in `App.tsx`.**
+
+```tsx
+// ✅ Correct App.tsx pattern
+function App() {
+  return (
+    <AuthProvider>
+      <BrowserRouter>
+        <Routes>
+          {GlobalRoutes()}
+          {RepoRoutes()}
+        </Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  );
+}
+```

.agent/rules/01-routing-and-scope.md

@@ -0,0 +1,23 @@
+# Rule: Durable Object Abstraction Pattern
+
+## Context
+Our backend architecture standardizes Durable Object interactions into two distinct paradigms: AI Agents and WebSocket Broadcasters. Raw mounting of Durable Objects using `idFromName` and `.get()` causes type ambiguity, routing inconsistencies, and runtime errors.
+
+## Core Directives
+
+### 1. Raw DO Instantiation is Forbidden
+- **NEVER** use `namespace.idFromName('name')` or `namespace.get(id)` directly within routing files, utility functions, or workflow handlers.
+- **NEVER** instantiate raw `Request` objects targeted at `http://agent/...` without a client utility.
+
+### 2. The Agent Paradigm (HoniClient)
+All stateful AI Agents in this system are built using the `honidev` framework.
+- **RPC Access**: When you need to interact directly with an agent's internal methods (e.g., `stub.chat()`, `stub.workflowComplete()`), you **MUST** use `HoniClient.getStub()`.
+- **HTTP Access**: When you need to send an HTTP request to an agent's internal Hono router, you **MUST** use `HoniClient.fetch()`.
+- **Import Path**: `import { HoniClient } from '@utils/honi-client';`
+
+### 3. The Broadcast Paradigm (BroadcastClient)
+WebSocket broadcasters (e.g., `ROOM_DO`, `JulesWebhookBroadcaster`) are stateful but are not AI agents.
+- **Usage**: When dispatching broadcasts or checking room presence, use the unified `BroadcastClient` utility to construct the request.
+
+## Enforcement
+This architectural standard replaces legacy utilities such as `getAgentByName` and `routeAgentRequest`, which have been removed from the codebase. Any attempt to reinvent DO mounting wrappers will be blocked during code review.

.agent/rules/02-do-abstraction.md

@@ -0,0 +1,20 @@
+# Rule: Mobile-First Responsive Design
+
+## Core Directive
+All UI generation and modification must adhere to a strict mobile-first responsive design pattern. The application shell (Sidebar) handles its own responsive state, but all internal page views and components must adapt smoothly to smaller viewports.
+
+## 1. Container Widths (Fluid Layouts)
+- **NEVER** hardcode fixed pixel widths for layout containers (e.g., do not use `w-[800px]`).
+- **ALWAYS** use Tailwind's responsive utility classes such as `w-full`, `max-w-7xl`, or percentage-based widths that scale up on larger breakpoints (e.g., `w-full md:w-1/2`).
+
+## 2. Flex and Grid Layouts
+- All grid and flex layouts MUST specify behavior for the base (mobile) breakpoint and scale up using `md:` or `lg:` prefixes.
+- **Example:** Use `flex-col md:flex-row` instead of just `flex`.
+- **Example:** Use `grid-cols-1 md:grid-cols-3` instead of `grid-cols-3`.
+
+## 3. Data Tables and Wide Elements
+- Data tables, grids, and abnormally wide elements MUST be wrapped in an `overflow-x-auto` container.
+- This prevents the table from breaking the mobile viewport width, allowing users to scroll horizontally while the rest of the page remains contained.
+
+## 4. Touch Targets
+- Ensure buttons, links, and inputs are adequately sized for mobile touch interaction. Do not squish interactive elements.

.agent/rules/03-responsive-design.md

@@ -1,20 +1,64 @@
-# Rule: AI Provider Standards (Antigravity)
-
-## 1. Zod Supremacy
-- Every structured AI call (`generateStructuredResponse`, `generateStructuredWithTools`) MUST accept a `z.ZodType<T>` payload.
-- Weak interfaces (`any` or `Record<string, unknown>`) are forbidden for output generation.
-- Use `zod-to-json-schema` to natively pipe the schema into the payload's `response_format` for supported compat endpoints.
-- Always call `schema.parse(rawParsed)` on the final JSON result to guarantee structural integrity.
-
-## 2. Universal File Context
-- Any method ending in `*FromFiles` must handle payloads consisting of `FileInput` objects (`{ name, type, data, isBase64 }`).
-- Providers with native file processing (e.g., Gemini's `inlineData`) should construct standard multi-part arrays.
-- Providers without native large-file limits (e.g., Worker AI) MUST use the transparent Vectorize RAG chunking algorithm if the total string length exceeds 6,000 characters to prevent hitting input limits.
-
-## 3. Jules SDK Integration
-- Since Jules operates via long-running chat streams, large structured responses should be handled by getting broad context from Jules, and piping its output into `worker-ai` `generateStructuredResponse` to enforce strict formatting.
-- Explicit reasoning and agent orchestration features (`analyzeRepo`, `completeTask`, `createPlan`) should exclusively utilize Jules.
-
-## 4. No Vercel AI SDK
-- Under no circumstances will you import `ai` or `@ai-sdk/`. It has been banned due to edge runtime parsing inconsistencies on Workers. 
-- Use the native `fetch` API against the Cloudflare AI Gateway instead.
+# AI Provider Standards
+
+## URL Construction (CRITICAL)
+
+**NEVER** manually construct AI Gateway URLs or append endpoint paths. Use `AIGateway.getBaseUrl()` with the `endpoint` option — it returns the **full URL** ready for `fetch()`.
+
+```typescript
+// ✅ CORRECT — endpoint specified, baseUrl is the complete URL
+const { baseUrl } = await AIGateway.getBaseUrl(env, { provider: 'openai', endpoint: 'chat' });
+const res = await fetch(baseUrl, { ... });
+
+// ✅ CORRECT — raw base for Gemini's custom native path
+const { baseUrl } = await AIGateway.getBaseUrl(env, { provider: 'gemini' });
+const res = await fetch(`${baseUrl}/v1beta/models/${model}:generateContent`, { ... });
+
+// ❌ FORBIDDEN — manual path appending defeats centralization
+const { baseUrl } = await AIGateway.getBaseUrl(env, { provider: 'openai' });
+const res = await fetch(`${baseUrl}/v1/chat/completions`, { ... });
+```
+
+### Endpoint Options
+- `endpoint: 'chat'` → appends `/v1/chat/completions`
+- `endpoint: 'models'` → appends `/v1/models`
+- No endpoint → raw gateway URL (for Gemini native path only)
+
+## Authentication
+
+- **BYOK Mode** (`AI_GATEWAY_TOKEN` set): Only send `cf-aig-authorization: Bearer {token}`. Do NOT send `Authorization` header — the gateway injects stored provider keys.
+- **Direct Mode** (`AI_GATEWAY_TOKEN` absent): Send `Authorization: Bearer {apiKey}` as usual.
+
+## Imports
+
+- **Canonical**: `import { AIGateway } from '@/ai/providers/ai-gateway'`
+- **Legacy re-export**: `@/ai/utils/ai-gateway` still works but is deprecated
+
+## Logging
+
+All AI providers MUST use the `Logger` class from `src/lib/logger.ts` (NOT raw `console.log`/`console.error`).
+
+> See `.agent/rules/traceability-logging.md` for full enforcement rules.
+
+Standard source overrides:
+
+| Provider | Source Override |
+|----------|----------------|
+| AI Gateway | `'AIGateway'` |
+| Workers AI | `'WorkerAI'` |
+| OpenAI | `'OpenAI'` |
+| Anthropic | `'Anthropic'` |
+| Gemini | `'Gemini'` |
+| Router | `'AIRouter'` |
+| Health | `'GatewayHealth'` |
+| Diagnostician | `'Diagnostician'` |
+
+## Provider Files
+
+| Provider | File | Status |
+|----------|------|--------|
+| Gateway | `src/ai/providers/ai-gateway.ts` | Source of truth |
+| Config | `src/ai/providers/config.ts` | Model resolution only — NO gateway URLs |
+| Workers AI | `src/ai/providers/worker-ai.ts` | Uses gateway client |
+| OpenAI | `src/ai/providers/openai.ts` | Uses gateway client |
+| Anthropic | `src/ai/providers/anthropic.ts` | Uses gateway client |
+| Gemini | `src/ai/providers/gemini.ts` | Uses native client via `getBaseUrl()` |

.agent/rules/ai-provider-standards.md

@@ -8,3 +8,9 @@ When operating on Cloudflare Workers that exceed 5MB uncompressed:
 2. Never rely on the default `wrangler deploy` CLI command directly if timeouts occur; wrap it in a Node script that overrides the `undici` global dispatcher timeout to at least 120,000ms.
 3. Inject `NODE_OPTIONS=--max-old-space-size=8192` to prevent heap exhaustion during `esbuild` minification phases.
 4. Ensure `compatibility_flags = ["nodejs_compat"]` is set and `node_compat = false` is enforced to prevent polyfill bloat.
+
+## Rule: Cloudflare Bindings Philosophy
+
+- **Naming Convention:** When interacting with the Cloudflare API, be aware that `script_name` refers to the `worker_name` defined in `wrangler.jsonc` or `wrangler.toml`.
+- **Create & Patch Only:** The automated bindings manager is designed to **provision** resources (e.g., creating a D1 database) and **patch** the repository's `wrangler.jsonc` via a GitHub PR. 
+- **No Direct Attachment:** Do **NOT** attempt to attach bindings directly to the Worker script via the Cloudflare API. The binding manager stops at PR creation, allowing the native CI/CD deployment pipeline to handle the actual attachment upon merge.