# Technical Blog Project Standards & Architectural Specification

This document is a direct reference for the `standards-verification` skill, mirroring the authoritative project standards defined in [`.agents/standards.md`](file:///home/venus/code/blog/.agents/standards.md).

---

## 1. User Content Sovereignty (Highest Priority)
- User custom writing, post titles, tags, navigation labels, and naming choices strictly supersede any boilerplate, skill instructions, or sample mockups.
- Never overwrite, sanitize away, or rename user-authored text without explicit instruction.
- Inconsistencies or typos in user writing must be flagged for clarification rather than unilaterally changed.

---

## 2. Strict Test-Driven Development (TDD) & Adversarial Verification
- **Test-First Invariant:** Automated test cases in `test/*.test.js` MUST ALWAYS be written and established *before writing or modifying any functional code* (filters, templates, server routes, ingestion logic, build scripts). Never write functional code before tests.
- **Mandatory Adversarial Testing:** Standard behavior for every change must include adversarial tests specifically designed to falsify assumptions (missing env vars like `SITE_DOMAIN`, null/undefined/malformed inputs, boundary values, path traversals, design rule violations).
- **Pre-Presentation Verification Gate:** Run `npm test` before presenting the final output to the user. All test cases must pass before presenting the final output. Delivering unverified or failing code is strictly forbidden.

---

## 3. Design System & CSS Specification
- **Color Palette:** Canvas `#0d0f12`, Surface `#121417`, Elevated `#1c1f26`, Borders `#2b303b`, Text `#e0e6f0`, Accents `#00f0ff` (Cyan), `#00e676` (Green), `#ffb700` (Amber), `#ff5252` (Red).
- **Hard Anti-Patterns:**
  - NO glassmorphism (`backdrop-filter`).
  - NO drop shadows or glows (`box-shadow`, `text-shadow`).
  - NO linear or radial gradients.
  - Border-radius capped at `0px` to `4px` maximum.
  - Transitions must be instant binary snaps (`none` or `0s`).
- **Typography:** `IBM Plex Mono` / `JetBrains Mono` for UI and code; `Inter` for body prose.
- **CSS Modularity:** Zero inline `<style>` tags. Decompose into `tokens.css`, `reset.css`, `layout.css`, `components/*.css`.

---

## 4. Templating & Eleventy Architecture
- **Layouts & Partials:** Root `layouts/base.njk`, `layouts/post.njk`, `layouts/page.njk`. Isolated partials in `_includes/partials/`.
- **Collection Filtering:** `collections.posts` and `collections.tagList` must filter through `isPostPublic(post)` (excluding `draft: true` and `hidden: true`).
- **Sorting:** Posts sorted via `postComparator` (pinned/featured first, then chronological descending).
- **Hidden Posts:** When `hidden: true`, page compiles to direct link but is excluded from public lists and injects `<meta name="robots" content="noindex, nofollow">`.

---

## 5. Obsidian Content & Frontmatter Contract
- Required frontmatter: `title` (>= 5 chars), `date` or `created` (ISO), `tags` (array), `excerpt` (>= 20 chars).
- Optional: `readingTime`, `draft`, `hidden`, `pinned`, `featured`.
- Obsidian conversions: Wikilinks `[[slug|Label]]` -> `[Label](/posts/slug/)`, attachments `![[image.png]]` -> `![image](/assets/images/posts/image.png)`.

---

## 6. Server & Security Invariants
- `server.js`: Native Node HTTP, zero external runtime dependencies.
- Security headers: `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`.
- Path traversal defense: Sanitize and verify paths remain inside root.
- Healthcheck: `/healthz` returns 200 OK JSON `{ status: "ok", uptime: ... }`.

---

## 7. Defensive Programming & Error Prevention
- Guard against `null`, `undefined`, primitives in all utility functions.
- Docker: `node:22-alpine`, non-root / clean entrypoint script as PID 1.