Refactor: Implement Dual-Scope Routing paradigm, UI mobile responsiveness, and DO HoniClient abstraction

Author: jmbish04

.agent/rules/01-routing-and-scope.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/02-do-abstraction.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/03-responsive-design.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/cloudflare-deployments.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.

.agent/rules/cloudflare-standards.md

@@ -0,0 +1,6 @@
+# Cloudflare Worker Standards (2026)
+
+- **Routing & Validation**: All APIs must exclusively utilize `Hono` alongside `@hono/zod-openapi` to enforce strict request schemas and automate documentation generation.
+- **OpenAPI Enforcement**: Every Worker project must host `/openapi.json` (OpenAPI v3.1.0) and include a mounted `/scalar` and `/swagger` viewer UI.
+- **AI Operations**: Standardize on the official `openai` SDK. Connections must be instantiated securely by configuring the `baseURL` to point directly to Cloudflare AI Gateway. 
+- **Types & Configuration**: Environment typing is maintained strictly through `wrangler.jsonc` (not `wrangler.toml`), and synchronized via `wrangler types`. Manual mapping of types is deprecated.

.agent/rules/d1-drizzle-governance.md

@@ -0,0 +1,140 @@
+---
+description: Strict governance rules for D1 database instances, Drizzle ORM usage, schema changes, and migration management in the core-github-api project.
+---
+
+# D1 & Drizzle ORM Governance Rules
+
+## Table Instance Ownership
+
+Every table in this project belongs to exactly ONE D1 binding. When in doubt, check this table first:
+
+| D1 Binding | Migration Config | Owns |
+|-----------|-----------------|------|
+| `DB` | `drizzle.config.core.ts` → `migrations/core/` | All application logic tables: `system_logs`, `audit_logs`, `automation_logs`, `repos`, `prs`, `reviews`, `health_*`, `cloudflare_changelog`, `jules_*`, `discord_*`, `agent_*`, `project_*` |
+| `DB_WEBHOOKS` | `drizzle.config.webhooks.ts` → `migrations/webhooks/` | Raw GitHub event tables ONLY: `webhook_deliveries`, `pull_request`, `push`, `check_run`, `workflow_run`, `webhook_configs`, `searches`, `repoAnalysis`, `dailyTrends`, `trendingRepos` |
+
+## ORM Client Selection
+
+| Situation | Client to Use | Import |
+|-----------|--------------|--------|
+| Reading/writing any table on `DB` | `getDb(env.DB)` | `import { getDb } from '@db'` |
+| Reading/writing any table on `DB_WEBHOOKS` | `getWebhooksDb(env.DB_WEBHOOKS)` | `import { getWebhooksDb } from '@db'` |
+| ❌ FORBIDDEN | `drizzle(env.DB)` or `drizzle(env.DB_WEBHOOKS)` | Never — always pass schema via the getters |
+
+## Pre-Table-Creation Protocol (MANDATORY)
+
+Before creating any new Drizzle table:
+
+1. **Scan existing tables** — run the following and read the relevant schema files:
+   ```bash
+   grep -r "sqliteTable" src/backend/src/db/schemas/ --include="*.ts" -l
+   ```
+2. **Evaluate reuse** — can you add a column to an existing table? Is there a table in a different domain that serves this purpose?
+3. **Only if no existing table fits** — create a new one
+4. **Assign to correct D1 instance** — use the ownership table above to determine which Drizzle config and migration dir to use
+5. **Add to the correct barrel** — update the domain's `index.ts` so it is picked up by `schema.ts`
+
+## Schema File Locations
+
+```
+src/backend/src/db/
+├── schema.ts                     ← master barrel (all domains, used by DB/core)
+├── schemas/
+│   ├── index.ts                  ← re-exports all domains
+│   ├── agents/
+│   ├── app/                      ← cloudflare_changelog, etc.
+│   ├── discord/
+│   ├── github/
+│   │   └── webhooks.ts           ← webhook event tables (owned by DB_WEBHOOKS)
+│   ├── logs/                     ← system_logs, audit_logs, health_* (owned by DB)
+│   ├── ops/
+│   ├── webhooks/
+│   │   └── automations.ts        ← automation_logs, webhook_configs
+│   └── ...
+└── index.ts                      ← exports getDb() and getWebhooksDb()
+```
+
+## Migration Discipline
+
+- **NEVER** edit files in `migrations/core/` or `migrations/webhooks/` directly
+- Generate: `pnpm run db:generate:core` or `pnpm run db:generate:webhooks`
+- Apply: `pnpm run migrate:remote:core` or `pnpm run migrate:remote:webhooks`
+- Full reset: `pnpm run db:reset` (creates fresh DB instances, archives old migrations)
+- Manual repair is ONLY permitted if a migration script fails AND the user explicitly authorizes it
+
+## Fresh Instance Reset Protocol
+
+When you need a clean slate (structural errors, wrong table locations, D1 corruption):
+
+```bash
+pnpm run db:reset
+# Then, after deploy completes:
+pnpm run db:seed:prep   # prepare seed files from pre-delete export
+pnpm run db:seed:run    # apply seeds to fresh instances
+```
+
+### What `pnpm run db:reset` does:
+1. Reads current D1 UUIDs **dynamically from `wrangler.jsonc`** — no hardcoded constants
+2. Exports all row data to `scripts/db/data_exports/{timestamp}/` (SQL + JSON) before deletion
+3. Deletes old D1 instances via CF REST API
+4. Creates new fresh instances with canonical names
+5. Updates `wrangler.jsonc` with new UUIDs
+6. Archives old migration history to `migrations/_archive/`
+7. Chains: `db:generate:all → migrate:remote:all → deploy`
+
+### Seeding After Reset:
+
+**Step 1:** `pnpm run db:seed:prep [-- --export-dir scripts/db/data_exports/TIMESTAMP]`
+- Reads the JSON export from the pre-delete backup
+- Applies truncation limits (e.g. `system_logs` → last 2000 rows, `webhook_deliveries` → last 500)
+- Chunks INSERT statements to stay within D1 limits: 100 bound params/query, 90 KB/statement
+- Writes `scripts/db/seeds/{timestamp}/DB.seed.sql` and `DB_WEBHOOKS.seed.sql`
+
+**Step 2:** `pnpm run db:seed:run [-- --seeds-dir scripts/db/seeds/TIMESTAMP]`
+- Tries bulk `--file` execution first (fastest)
+- Falls back to statement-by-statement with D1 error keyword detection
+- Retries on transient overload, aborts on fatal errors (column_notfound, schema mismatch)
+- Prints instructive fix guidance for every known D1 error type
+
+### D1 Execution Limits (Hardcoded in scripts as source of truth):
+| Limit | Value | Source |
+|-------|-------|--------|
+| Max bound params per query | 100 | CF hard limit |
+| Max SQL statement length | 100 KB (scripts use 90 KB) | CF hard limit |
+| Max query duration | 30 seconds | CF hard limit |
+| Safe INSERT batch size | 100 rows | CF recommendation |
+| Max D1 database size | 10 GB | CF hard limit |
+
+⚠️ **Do NOT put seed files in `migrations/` directories** — wrangler will try to apply them as migrations.
+
+## Health Monitors for D1 Staleness
+
+Three health checks run as part of `POST /api/health/run`:
+
+| Check ID | File | What it detects |
+|----------|------|-----------------|
+| `webhook_staleness` | `health/checks/webhook-staleness.ts` | `webhook_deliveries` freshness vs latest GitHub API event (fails if >24h lag or empty) |
+| `log_staleness` | `health/checks/log-staleness.ts` | `system_logs` freshness (fails if empty or >1 day old) |
+| `d1_table_scan` | `health/checks/d1-table-scan.ts` | All tables in both instances — flags empty (0 rows) or stale (>30 days) |
+
+To manually check D1 staleness at any time:
+```bash
+# Quick row count check
+wrangler d1 execute DB --remote --command "SELECT count(*) FROM system_logs;"
+wrangler d1 execute DB_WEBHOOKS --remote --command "SELECT count(*) FROM webhook_deliveries;"
+
+# Or trigger the full health suite
+curl -X POST https://core-github-api.hacolby.workers.dev/api/health/run | jq '.results[] | select(.name | test("Staleness|Table Scan"))'
+```
+
+## Adding a New Table — Checklist
+
+```
+[ ] Scanned existing schemas, no suitable table found
+[ ] Determined correct D1 instance (DB vs DB_WEBHOOKS)
+[ ] Created file in correct schemas/<domain>/ directory
+[ ] Exported from schemas/<domain>/index.ts
+[ ] Ran pnpm run db:generate:<core|webhooks>
+[ ] Reviewed generated migration SQL (do not edit it)
+[ ] Ran pnpm run migrate:remote:<core|webhooks>
+```

.agent/rules/error-handling.md

@@ -28,7 +28,7 @@ When a frontend component catches an error, you **MUST** pass the literal error
       handleGlobalError(err);
   }
   ```
-- **Forbidden**: Do not use `console.error(err)` as the sole failure mechanism. Do not write local `<Alert variant="destructive">` blocks for API failures unless it's a localized form validation constraint.
+- **Forbidden**: Do not use `console.error(err)` or raw `toast.error()` directly for system or API errors. Do not write local `<Alert variant="destructive">` blocks for API failures unless it's a localized form validation constraint. Use `handleGlobalError()` exclusively, which handles deduplication and backend metric dispatching automatically.
 
 ## 3. Strict Passthrough
 Agents must ensure that backend routes return the actual error string generated by the failed service (e.g. GitHub API 404s, Stripe 402s).