blog/.agents/skills/standards-verification/references/standards.md

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.

---

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.