diff --git a/.jules/archie.md b/.jules/archie.md new file mode 100644 index 00000000..6abc4853 --- /dev/null +++ b/.jules/archie.md @@ -0,0 +1,3 @@ +2026-08-24 - Establish Core Architectural Governance & Codify Schema Validation ADR +Learning: Implicit repository conventions for Zod boundary validation and Cloudflare/Render target separation lacked explicit AI Agent Directives and master index documentation, risking agent architectural drift. +Action: Standardized ADR template formatting, established `docs/adr/README.md` master index and `docs/tech-radar.md` repository tech radar, and codified strict Zod boundary validation into `docs/adr/0002-strict-zod-schema-validation.md`. diff --git a/docs/adr/0001-cloudflare-production-render-jules.md b/docs/adr/0001-cloudflare-production-render-jules.md index 1070a827..a44b55e8 100644 --- a/docs/adr/0001-cloudflare-production-render-jules.md +++ b/docs/adr/0001-cloudflare-production-render-jules.md @@ -1,18 +1,26 @@ -# ADR 0001: Cloudflare as production, Render as Jules test env +# 0001. Cloudflare as Production, Render as Jules Test Environment -- Status: Accepted -- Date: 2026-08-24 +- **Status:** Accepted +- **Date:** 2026-08-24 +- **Deciders:** Autonomous Architect (Archie) / Repository Analysis ## Context -The site can build two ways: Cloudflare Workers (static + `@astrojs/cloudflare`) or a Node standalone server when `RENDER=true` (`@astrojs/node`). Prod already runs at https://me.alehar.workers.dev/. We need a clear split so Google Jules can debug against a Node environment without treating that path as a second production or failover. +The site can build two ways: Cloudflare Workers (static + `@astrojs/cloudflare`) or a Node standalone server when `RENDER=true` (`@astrojs/node`). Production already runs at https://me.alehar.workers.dev/. We need a clear architectural split so automated AI agents (such as Google Jules) can debug against a Node server environment without treating that path as a second production instance or failover target. ## Decision -Production is Cloudflare Workers only. Render is a test environment for Google Jules (Node server via `render.yaml`). It is not a second prod and not a failover. +Production is strictly Cloudflare Workers + Assets. Render is exclusively a isolated test environment for Google Jules debugging (Node server via `render.yaml`). Render is not a second production environment and must never be treated as a failover target. -## Consequences +## Consequences & Tradeoffs -- Ship and operate prod on the Cloudflare Worker (`wrangler.jsonc`, `src/cloudflare-worker.ts`). -- Keep the Render Node path for Jules debugging only; expect AI/KV and other Workers bindings to be absent or stubbed there (`src/env/cloudflare-workers.node.ts`). -- Docs and ops language should call Cloudflare production and Render the Jules test env. +- **Positive:** Clear separation of deployment targets; production operates entirely on serverless edge infrastructure with ultra-low latency and native Cloudflare Workers assets. +- **Negative / Risks:** Development and test environments running on Node (such as Render) must mock or stub Cloudflare Workers runtime bindings (`src/env/cloudflare-workers.node.ts`). +- **Adoption Readiness:** Fully adopted and active in production. + +## Directives for AI Agents + +- **Do:** Ship and operate production strictly on the Cloudflare Workers target (`wrangler.jsonc`, `src/cloudflare-worker.ts`). +- **Do:** Refer to Cloudflare as "production" and Render as "Jules test environment" across logs, documentation, and PR descriptions. +- **Don't:** Treat Render as a production target, secondary region, or failover system. +- **Don't:** Rely on native Cloudflare Workers bindings (e.g. KV, AI bindings) when running inside the Render Node test environment. diff --git a/docs/adr/0002-strict-zod-schema-validation.md b/docs/adr/0002-strict-zod-schema-validation.md new file mode 100644 index 00000000..ae05af97 --- /dev/null +++ b/docs/adr/0002-strict-zod-schema-validation.md @@ -0,0 +1,27 @@ +# 0002. Strict Zod Schema Validation for Content Collections and API Boundaries + +- **Status:** Accepted +- **Date:** 2026-08-24 +- **Deciders:** Autonomous Architect (Archie) / Repository Analysis + +## Context + +The repository handles unstructured or dynamic inputs across several key system boundaries: Astro Markdown/MDX content collections, environment variable configurations, and edge API request payloads. Without explicit schema validation at runtime and build time, unvalidated input can lead to runtime exceptions (`undefined` field access), type safety erosion, and agent drift when generating content or handling API payloads. + +## Decision + +All external data, content collections, environment variables, and dynamic API request payloads must be strictly validated using Zod schemas at runtime and compile-time boundaries. TypeScript interfaces for data collections must be derived directly from Zod schemas using `z.infer`. + +## Consequences & Tradeoffs + +- **Positive:** Eliminates runtime `undefined` property access errors; provides a single source of truth for application data types; prevents untyped agent drift during content generation and API refactoring. +- **Negative / Risks:** Minor build-time overhead for schema parsing; requires keeping Zod schemas synchronized when adding new content fields. +- **Adoption Readiness:** Fully adopted across Astro content collections (`src/content.config.ts`), environment handling (`src/env/`), and edge endpoints (`src/pages/api/`). + +## Directives for AI Agents + +- **Do:** Declare and export explicit Zod schemas in `src/content.config.ts` or endpoint modules before consuming external data or content collections. +- **Do:** Derive TypeScript types via `z.infer` rather than declaring redundant manual interface declarations. +- **Do:** Use `z.ZodError['issues']` or safe guards when referencing Zod error types in tests to avoid Zod 4 deprecation warnings. +- **Don't:** Bypass schema validation using type assertions (`as MyType`), explicit `any`, or `@ts-ignore`. +- **Don't:** Parse API request bodies without using `.safeParse()` or `.parse()` at the boundary handler. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 00000000..e39bd13d --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,17 @@ +# Architecture Decision Records (ADRs) + +This directory contains Architecture Decision Records (ADRs) for the repository. ADRs document significant architectural decisions, context, trade-offs, and explicit directives for human developers and autonomous AI agents. + +## ADR Master Index + +| ID | Title | Status | Date | Summary | +| -------------------------------------------------- | ----------------------------------------------------------------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| [0001](0001-cloudflare-production-render-jules.md) | Cloudflare as Production, Render as Jules Test Environment | Accepted | 2026-08-24 | Production is Cloudflare Workers + Assets; Render is strictly a test environment for Google Jules debugging. | +| [0002](0002-strict-zod-schema-validation.md) | Strict Zod Schema Validation for Content Collections and API Boundaries | Accepted | 2026-08-24 | All boundary inputs (content, env vars, edge APIs) must be validated with Zod schemas and TypeScript types inferred via `z.infer`. | + +## ADR Lifecycle & Rules + +1. **Sequential Numbering:** ADR files must strictly follow `NNNN-[title].md` format (e.g. `0001-...md`, `0002-...md`). +2. **Master Index Sync:** Every new, updated, or status-changed ADR must be reflected in the index table above. +3. **AI Agent Directives:** Every ADR must contain a `## Directives for AI Agents` section establishing explicit `Do` and `Don't` boundaries to prevent AI agent architectural drift. +4. **Non-Destructive Modifications:** ADRs must not be deleted or superseded without creating or linking the replacement ADR in the same change. diff --git a/docs/tech-radar.md b/docs/tech-radar.md new file mode 100644 index 00000000..24f144d9 --- /dev/null +++ b/docs/tech-radar.md @@ -0,0 +1,76 @@ +# Repository Tech Radar + +This document tracks technologies, frameworks, infrastructure patterns, and workflows used across the repository. It provides ground-truth context for human engineers and autonomous AI agents. + +## Quadrants & Technology Status + +### 1. Frameworks & Runtimes + +- **Adopt:** + - **Astro (v7+):** Primary static site generator and dynamic server-rendering framework. + - **TypeScript (Strict Mode):** Mandatory language choice for type-safe application logic and data schemas. + - **Node.js (>=22.12):** Standard runtime engine for local development, CI pipelines, and Jules test runner. +- **Trial:** + - **Cloudflare Workers `@astrojs/cloudflare` adapter:** Edge adapter for serverless asset routing and pre-rendering. +- **Assess:** + - **WebGPU / Native Canvas Shaders:** Evaluation for potential interactive background visuals in lab components. +- **Hold:** + - **React / Vue / Svelte Component Frameworks:** Avoid client UI runtime frameworks; leverage static HTML + Vanilla Web Components to keep client JS minimal. + +--- + +### 2. Infrastructure & Cloud + +- **Adopt:** + - **Cloudflare Workers + Assets:** Unified serverless deployment target for production site hosting (`wrangler.jsonc`). + - **Sentry (`@sentry/astro`):** Client and edge runtime monitoring and error performance tracking. +- **Trial:** + - **Render Node Standalone Server (`render.yaml`):** Isolated testing environment for Google Jules debugging (see [ADR 0001](adr/0001-cloudflare-production-render-jules.md)). +- **Assess:** + - **Cloudflare Vectorize / AI Workers:** Potential future integration for local semantic RAG queries. +- **Hold:** + - **Deprecated Cloudflare Pages Direct Uploads:** Replaced by unified Workers-First model (`wrangler.jsonc`). + - **Parallel Manual Production CI Deploys:** Cloudflare Git integration owns production deployments on `main`. + +--- + +### 3. Tooling & AI Workflows + +- **Adopt:** + - **Vitest:** Primary Unit & Integration testing suite. + - **ESLint & Prettier:** Mandatory code formatting and static analysis rules. + - **Husky & lint-staged:** Pre-commit hooks for automated formatting and linting verification. + - **Jules & Autonomous Agent Suite (Archie, Kinetic, Stratus, Palette, Sentinel, Engine, etc.):** Autonomous agent ecosystem. + - **MCP Servers (`mcp_config.json`):** Model Context Protocol integrations for local documentation and tooling. +- **Trial:** + - **Playwright (Python/Node):** Visual verification screenshotting and E2E smoke tests. +- **Assess:** + - **Codecov Bundle Analysis:** Tracking bundle sizes and coverage metrics in PR workflows. +- **Hold:** + - **Commit-time Writes to Protected Main Branch:** Release scripts must create GitHub releases rather than committing version tags directly back to `main`. + +--- + +### 4. Patterns & Architecture + +- **Adopt:** + - **Static-First Pre-rendering:** Pre-render pages to static HTML by default (`output: "static"`). + - **Zod Boundary Validation:** Validate all external content collections, environment variables, and API payloads via Zod schemas (see [ADR 0002](adr/0002-strict-zod-schema-validation.md)). + - **Vanilla CSS Glassmorphism:** Scoped CSS with custom properties ('Northern Lights' aesthetic); no CSS utility frameworks. + - **Workers-First Binding Pattern:** Uniform environment variable binding and asset routing via `wrangler.jsonc`. +- **Trial:** + - **Astro View Transitions (`astro:page-load`):** Smooth client navigation with strict initialization event handler listener patterns. +- **Assess:** + - **Edge Caching Header Customization:** Micro-optimizations for static asset edge cache TTL. +- **Hold:** + - **Tailwind CSS / CSS Frameworks:** Banned. Use Vanilla scoped CSS only. + - **Any / `@ts-ignore` Type Bypasses:** Banned. All code must pass strict TypeScript checks. + +--- + +## Ring Definitions + +- **Adopt:** High confidence, production-proven in this repository. Default choice for new work. +- **Trial:** High potential with low risk. Ready for isolated usage in minor features or experimental routes. +- **Assess:** Worth tracking and evaluating trade-offs; not yet recommended for active production code. +- **Hold:** Phasing out or proven problematic in our setup. Banned for new work.