chore: merge jules-bug-smash into main - rescue all staged work

Author: jmbish04

.agent/rules/000-bootstrap.md

@@ -0,0 +1,15 @@
+---
+trigger: always_on
+---
+
+# 000: BOOTSTRAP & PROTOCOL CHECK
+**CRITICAL: Mandatory Pre-flight Check.**
+
+Before starting any task, you must verify the following from `AGENTS.md`:
+
+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.
+
+**STOP**: If you have not explicitly read `AGENTS.md` in this session, do so now.

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

@@ -0,0 +1,21 @@
+---
+trigger: always_on
+---
+
+# CORE DIRECTIVE: PROTOCOL ENFORCEMENT
+
+**CRITICAL:** Before performing ANY task, you MUST synchronize your internal state with the project's specific constraints.
+
+1. **Mandatory Documentation Review:**
+   - You MUST read the `AGENTS.md` file in the root directory. It contains the workspace architecture and pnpm protocols.
+   - You MUST read ALL files in the `.agent/rules/` directory to understand the coding standards (Drizzle, Shadcn, Astro).
+
+2. **Workspace Verification:**
+   - Confirm if the task involves the `frontend` or `root/backend`.
+   - Apply the `pnpm --filter` protocol defined in `AGENTS.md`.
+
+3. **Validation Step:**
+   - If you have not read `AGENTS.md` in the current session, STOP and read it now. 
+   - Failure to follow the `pnpm` installation rules defined in `AGENTS.md` will result in environment corruption.
+
+**DO NOT proceed with code generation until you have confirmed the pnpm workspace structure.**

.agent/rules/AGENT_GOVERNANCE.md

@@ -0,0 +1,24 @@
+---
+trigger: always_on
+---
+
+# AGENT & WORKFLOW GOVERNANCE
+
+## 1. The Manager-Worker Pattern
+*   **Rule**: Agents (`extends Agent`) **MUST NOT** perform long-running blocking tasks (>10s).
+*   **Rule**: Long-running tasks (Cloning, Vectorizing, Scraping) **MUST** be offloaded to Cloudflare Workflows (`extends WorkflowEntrypoint`).
+*   **Rule**: Agents act as "Managers" (State/Decision); Workflows act as "Workers" (Execution).
+
+## 2. Tool Integration (MCP)
+*   **Constraint**: Do NOT import Node.js-exclusive packages (e.g., `fs`, `child_process`) directly into the Worker.
+*   **Strategy**: Adapt the *logic* of official tools into the Agents SDK `sql`-backed state or stateless `Octokit` calls.
+*   **Schema**: All tools must strictly define Zod schemas for the Agents SDK to generate valid MCP interfaces.
+
+## 3. Sandbox Usage
+*   **Lifecycle**: Sandboxes are ephemeral. Data must be extracted (to R2, D1, or Vectorize) before the `step` completes.
+*   **Security**: Never pass raw user input directly to `sandbox.exec()`. Sanitize command arguments.
+
+## 4. Vectorization & RAG
+*   **Chunking**: Code must be chunked (e.g., by function/class) before embedding.
+*   **Model**: Use `@cf/baai/bge-large-en-v1.5` for embeddings (1024 dimensions).
+*   **Metadata**: Upserts MUST include `{ repo, filepath, commit_sha }`.

.agent/rules/HEALTH_GOVERNANCE.md

@@ -0,0 +1,32 @@
+# Health Check Governance
+
+## Rule: Every New Module Must Register a Health Check
+
+When adding a new domain module under `backend/src/`, you **MUST**:
+
+1. Create a `health.ts` file co-located with the module
+2. Export `checkHealth(env: Env): Promise<HealthStepResult>`
+3. Register the check in `backend/src/health/coordinator.ts` → `CODE_CHECKS` array
+4. Assign a `HealthCategory` from the union in `backend/src/health/types.ts`
+
+## Rule: Dynamic Tests via D1
+
+Runtime endpoint monitoring uses the `health_test_definitions` table. CRUD is available at:
+
+- `GET /api/health/tests` — list all
+- `POST /api/health/tests` — create (Zod-validated)
+- `DELETE /api/health/tests/:id` — remove
+
+## Rule: AI Remediation
+
+Failed health checks automatically receive AI-powered remediation hints via `analyzeFailure()`. These are stored in the `ai_suggestion` column of `health_results`.
+
+## Rule: Cron Schedule
+
+Health suite runs weekly via cron `0 3 * * 0` (Sundays 3AM UTC).  
+On-demand runs are available via `POST /api/health/run`.
+
+## Rule: Frontend Sync
+
+The frontend at `/health` **must** display all categories defined in `CATEGORY_META` in `Health.tsx`.
+When adding a new `HealthCategory` to `types.ts`, also add an entry to the frontend registry.

.agent/rules/actions-llm.md

@@ -0,0 +1,11 @@
+# GitHub Actions LLM Rules
+
+## 1. Resilience
+
+- Always use `response_format={"type": "json_object"}` when interacting with `gpt-oss-120b` for data extraction.
+- Implement `try/except` blocks around the LLM call to prevent a single bad generation from crashing the CI pipeline.
+
+## 2. Dependency Management
+
+- Keep scripts self-contained within the YAML (using `cat <<EOF`) for simple tasks, or use a dedicated `scripts/` folder for complex ones.
+- Prioritize standard libraries (`openai`, `pydantic`) over experimental ones to ensure stability in the CI runner.

.agent/rules/agent-registry.md

@@ -0,0 +1,20 @@
+# Rule: Agent Registry and Dynamic UI
+
+## 1. Dynamic UI Consumption
+
+- Frontend agent selectors, wizards, and sidebars (e.g., `AgentSidebar.tsx`) **MUST NEVER** hardcode the list of available specialist agents.
+- All dynamic agent discovery must occur via the `GET /api/agents/specialists` REST endpoint. This ensures the backend remains the single source of truth for agent capabilities, routing, and availability.
+
+## 2. The Specialist Pattern
+
+- Avoid creating numerous bespoke subclasses of `HonoBaseAgent` (e.g., `DataAgent`, `UXAgent`, `SREAgent`) unless they require fundamentally distinct toolsets or event lifecycles.
+- Default to using **ONE** flexible `SpecialistAgent` class.
+- Dictate the specific persona dynamically at runtime by overriding the `systemPrompt` or passing a `specialty` configuration parameter when the frontend initiates the session.
+- **Why?** This prevents sprawling class files, keeps the agent execution logic DRY, and enables the system to spin up arbitrary expert subsets without code deployments.
+
+## 3. Plan Generation Output
+
+- The ultimate goal of a Workshop or Consultation flow is actionable output.
+- Specialist Agents should be equipped with a `save_plan(plan: JSON)` tool.
+- When the agent and user align on a roadmap, the agent must invoke `save_plan` to persist the structured JSON to the `projects`, `plans`, or `todos` table via Drizzle.
+- The UI should then react to this database mutation (e.g., by advancing the Wizard, redirecting to the Kanban board, or pushing a toast).

.agent/rules/ai-providers.md

@@ -0,0 +1,12 @@
+# Protocol: AI Provider Routing & Resolution
+
+**MANDATORY IMPORT PATH**: Agents must _always and exclusively_ import AI functions from `@/ai/providers`.
+**FORBIDDEN IMPORTS**: It is _never_ acceptable to import directly from specific provider files (e.g., `ai/providers/openai`, `ai/providers/gemini`) or the index file explicitly (e.g., `ai/providers/index`).
+
+**FUNCTION USAGE**: When using functions like `generateText`, `generateStructuredResponse`, etc., the agent should specify the `provider` and `model` arguments when known.
+
+**FALLBACK BEHAVIOR**:
+
+- If no provider or model is provided by the caller, the system relies on the `index.ts` routing to default to `worker-ai`, which then utilizes its internal business logic to select the correct fallback model.
+- Similarly, if a provider is specified but no model is provided, the specific provider module's logic determines the default model.
+- Agents should not hardcode default models unless explicitly required by the business logic.

.agent/rules/ai-routing.md

@@ -0,0 +1,5 @@
+# AI Routing & Fallback Rules
+
+- **Silent Failures:** Never allow a third-party AI provider failure to crash the request if a `worker-ai` equivalent model can handle the prompt.
+- **Type Safety:** Do not alter the return types (`string`, `T`) of the core generation functions to include metadata. Always use the `onFallback` callback mechanism in `AIOptions` to bubble up execution state.
+- **Observability:** Every fallback event must be aggressively logged to D1 to track provider reliability and API Gateway latency over time.

.agent/rules/ai-rules.md

@@ -0,0 +1,14 @@
+# Rule: AI Provider & Structured Responses
+
+## 1. Structured Output Mandate
+
+- **CRYSTAL CLEAR RULE**: ANYTIME the AI model is being instructed to respond with a structured response (JSON), you **MUST** use `generateStructuredResponse` or `generateStructuredWithTools` exported from `@/ai/providers`.
+- **FORBIDDEN**: Do not rely on native Agent SDK schemas (e.g. `outputType: MySchema as any` in `@openai/agents`). These frequently fail to map correctly through the Cloudflare AI Gateway or result in brittle string parsing.
+
+## 2. The Extraction Pattern (Agents with Tools)
+
+If you are running an autonomous Agent that requires tool usage (e.g., `HealthDiagnostician` or `ResearchAgent`):
+
+1. Configure the Agent to output standard text/markdown (`outputType` must NOT be explicitly defined).
+2. Await the Agent's `finalOutput` inside the execution loop.
+3. Pass that string into `generateStructuredResponse` along with your Zod schema (converted via `zodToJsonSchema`) to strictly extract and type the final JSON object. This ensures Gateway compatibility while guaranteeing Zod-verified JSON.

.agent/rules/alerts-standards.md

@@ -0,0 +1,62 @@
+# Alerts Standards
+
+## 1. The `createAlert()` Contract
+
+Every new feature that may fail, produce notable events, or require user attention **MUST** emit alerts using the canonical `createAlert()` function:
+
+```typescript
+import { createAlert } from "@alerts";
+
+await createAlert(env, {
+  type: "deployment", // AlertType: health | webhook | security | deployment | agent | info
+  severity: "error", // AlertSeverity: info | warning | error | critical
+  title: "Deploy failed",
+  description: "Wrangler exited with code 1. Check logs.",
+  link_url: "/webhooks", // Optional deep-link (relative path)
+  process_origin: "DeployWorkflow", // Human-readable origin
+});
+```
+
+`createAlert()` is fire-and-forget: it never throws, never blocks the main thread, and auto-gates based on `ALERTS_CONFIG` in KV.
+
+## 2. When to Emit Alerts
+
+| Scenario                            | Type         | Severity              |
+| ----------------------------------- | ------------ | --------------------- |
+| Health check failure                | `health`     | `error` or `critical` |
+| Webhook delivery failure (repeated) | `webhook`    | `warning`             |
+| Detected secret leak                | `security`   | `critical`            |
+| Worker deploy failure               | `deployment` | `error`               |
+| Agent task failure after retries    | `agent`      | `error`               |
+| Informational system event          | `info`       | `info`                |
+
+Do **NOT** alert on:
+
+- Expected/transient 4xx responses
+- Individual tool-call retries (only alert on final failure)
+- Debug or verbose logs (use `console.log` / `@logging` for those)
+
+## 3. Config-Gated Alerts
+
+`createAlert()` reads `ALERTS_CONFIG` from `KV_CONFIGS` at emit time. If a type is disabled or the master switch is off, the alert is dropped silently. You do not need to check the config yourself — the service handles it.
+
+## 4. Path Alias
+
+Always use `@alerts` — never use a relative import:
+
+```typescript
+// ✅ Correct
+import { createAlert } from "@alerts";
+
+// ❌ Wrong
+import { createAlert } from "../../alerts";
+```
+
+## 5. New Alert Types
+
+If you need a new alert type (beyond the 6 built-in), you must:
+
+1. Add it to `ALERT_TYPES` in `backend/src/db/schemas/app/alerts.ts`
+2. Add it to `AlertTypeFlags` in `backend/src/alerts/config.ts`
+3. Add its `TYPE_META` entry in `AlertTray.tsx` and `Alerts.tsx`
+4. Run `pnpm drizzle-kit generate` if schema changed