feat: added a hidden toggle availible in frontmatter which renders the note unlisted, also updated agent behavior with a compliance skill
This commit is contained in:
venus
@@ -0,0 +1,124 @@
|
||||
# Technical Blog Project Standards & Architectural Specification
|
||||
|
||||
This document defines the authoritative engineering, design, templating, and security standards for this technical publication codebase. All new implementations, pull requests, refactors, and debugging tasks must conform to these rules.
|
||||
|
||||
---
|
||||
|
||||
## 1. User Content Sovereignty (Highest Priority)
|
||||
|
||||
1. **User Edits Are Absolute Ground Truth:**
|
||||
- The user's custom writing, post titles, tags, navigation labels, terminology, and naming choices strictly supersede any boilerplate, skill instructions, or sample mockups (`sample-designs/*`).
|
||||
2. **No Unsolicited Modifications:**
|
||||
- Never overwrite, sanitize away, or rename user-authored text without explicit instruction.
|
||||
3. **Mandatory Clarification Gate:**
|
||||
- Inconsistencies or typos in user writing must be flagged for clarification rather than unilaterally changed.
|
||||
|
||||
---
|
||||
|
||||
## 2. Strict Test-Driven Development (TDD) & Adversarial Verification
|
||||
|
||||
1. **Test-First Invariant (Tests Before Code):**
|
||||
- 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 implement or modify production code prior to establishing tests.
|
||||
2. **Mandatory Adversarial Testing:**
|
||||
- Every functional implementation must include adversarial tests designed to actively falsify assumptions:
|
||||
- Missing or malformed configuration (e.g., unset `SITE_DOMAIN` must throw).
|
||||
- Corrupt or unexpected inputs (empty strings, `null`, `undefined`, unexpected types, HTML injections, path traversals, giant payloads).
|
||||
- Boundary values and edge cases.
|
||||
- Design rule violation assertions (0 instances of forbidden CSS patterns).
|
||||
- Link and anchor integrity checks.
|
||||
3. **Pre-Presentation Verification Gate:**
|
||||
- Before presenting the final output to the user, run `npm test`.
|
||||
- All test cases must pass before presenting the final output. Delivering unverified or failing code is strictly forbidden.
|
||||
|
||||
---
|
||||
|
||||
## 3. Design System & CSS Specification
|
||||
|
||||
Strict adherence to `sample-designs/design-specification.md` is mandatory.
|
||||
|
||||
### 3.1 Color Palette & Token Variables
|
||||
All colors must use standard CSS custom properties defined in `src/assets/css/tokens.css`:
|
||||
- Canvas: `var(--bg-canvas)` (`#0d0f12`)
|
||||
- Surface: `var(--bg-surface)` (`#121417`)
|
||||
- Elevated: `var(--bg-elevated)` (`#1c1f26`)
|
||||
- Borders: `var(--border-color)` (`#2b303b`)
|
||||
- Text: `var(--text-primary)` (`#e0e6f0`), `var(--text-muted)` (`#8a95a5`)
|
||||
- Accents: `var(--accent-cyan)` (`#00f0ff`), `var(--accent-green)` (`#00e676`), `var(--accent-amber)` (`#ffb700`), `var(--accent-red)` (`#ff5252`)
|
||||
|
||||
### 3.2 Hard Anti-Patterns (Forbidden)
|
||||
- **NO Glassmorphism:** Never use `backdrop-filter: blur(...)`.
|
||||
- **NO Drop Shadows or Glows:** `box-shadow: none;` and `text-shadow: none;` only.
|
||||
- **NO Gradients:** Never use `linear-gradient`, `radial-gradient`, or `conic-gradient`. Flat solid surfaces only.
|
||||
- **NO Rounded Bubbles:** `border-radius` is strictly capped between `0px` and `4px` maximum.
|
||||
- **NO Floaty / Delayed Transitions:** Hover and state transitions must be instant binary snaps (`transition: none;` or `transition: 0s;`).
|
||||
|
||||
### 3.3 Typography & Modularity
|
||||
- UI & Code: `IBM Plex Mono`, `JetBrains Mono`.
|
||||
- Body Prose: `Inter`.
|
||||
- CSS Modularity: Zero monolithic inline `<style>` tags in HTML. Decompose styles into `tokens.css`, `reset.css`, `layout.css`, and `components/*.css`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Templating & Eleventy Architecture
|
||||
|
||||
1. **Layout Inheritance (Nunjucks):**
|
||||
- Root layout: `src/_includes/layouts/base.njk`.
|
||||
- Post layout: `src/_includes/layouts/post.njk`.
|
||||
- Page layout: `src/_includes/layouts/page.njk`.
|
||||
- Modular reusable partials in `src/_includes/partials/` (`global-bar.njk`, `hero-tile.njk`, `post-card.njk`, `stats-sidebar.njk`, `code-box.njk`, `footer.njk`).
|
||||
2. **Collection Invariants:**
|
||||
- `collections.posts`: Must filter through `isPostPublic(post)` (excluding both `draft: true` and `hidden: true`) and sort using `postComparator` (prioritizing pinned/featured posts, then chronological descending).
|
||||
- `collections.tagList`: Must filter through `isPostPublic(post)` so draft or unlisted tags never leak into public category filters.
|
||||
3. **Hidden / Unlisted Post Contract:**
|
||||
- When frontmatter specifies `hidden: true`:
|
||||
- Excluded from public lists, indices, and tag aggregates.
|
||||
- Static page STILL compiles to `/posts/<slug>/index.html` and is accessible via direct URL.
|
||||
- Emits `<meta name="robots" content="noindex, nofollow">` in `<head>` to prevent search indexing.
|
||||
|
||||
---
|
||||
|
||||
## 5. Obsidian Content & Frontmatter Contract
|
||||
|
||||
1. **Frontmatter Schema:**
|
||||
```yaml
|
||||
title: "Article Title" # Required: string (>= 5 chars)
|
||||
date: 2026-09-23 # Required: ISO YYYY-MM-DD (or 'created')
|
||||
tags: ["#tag1", "#tag2"] # Required: non-empty YAML array
|
||||
excerpt: "Article summary..." # Required: string (>= 20 chars)
|
||||
readingTime: "5 MIN READ" # Optional: explicit override
|
||||
draft: false # Optional: boolean
|
||||
hidden: false # Optional: boolean (share by link only)
|
||||
pinned: false # Optional: boolean (prioritized to top)
|
||||
featured: false # Optional: boolean (featured pillar)
|
||||
```
|
||||
2. **Obsidian Syntax Normalization:**
|
||||
- Wikilinks: `[[target-slug|Custom Label]]` $\rightarrow$ `[Custom Label](/posts/target-slug/)`.
|
||||
- Wikilinks simple: `[[target-slug]]` $\rightarrow$ `[target-slug](/posts/target-slug/)`.
|
||||
- Attachments: `![[image.png]]` $\rightarrow$ ``.
|
||||
- Terminal alert callouts for `> [!NOTE]`, `> [!WARNING]`, etc.
|
||||
|
||||
---
|
||||
|
||||
## 6. Server & Security Invariants
|
||||
|
||||
1. **Native Runtime:**
|
||||
- `server.js` uses native Node standard library (`node:http`, `node:fs`, `node:path`) with zero external runtime dependencies.
|
||||
2. **Security Headers on All Responses:**
|
||||
- `X-Content-Type-Options: nosniff`
|
||||
- `X-Frame-Options: DENY`
|
||||
- `Referrer-Policy: strict-origin-when-cross-origin`
|
||||
3. **Path Traversal Defense:**
|
||||
- Sanitize all requested file paths using `path.resolve` and verify the resolved path remains rooted inside the target directory. Block `..` and malicious slug sequences.
|
||||
4. **Healthcheck Telemetry:**
|
||||
- `/healthz` and `/health` must respond with HTTP 200 JSON `{ status: "ok", uptime: <seconds> }`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Defensive Programming & Error Prevention
|
||||
|
||||
1. **Input Guarding:**
|
||||
- Never assume incoming arguments have expected shape. Always guard against `null`, `undefined`, non-objects, and primitive inputs (e.g., `item.data ?? item`).
|
||||
2. **Clean Container Contracts:**
|
||||
- Container images must use `node:22-alpine`.
|
||||
- Dynamic entrypoint (`entrypoint.sh`) must build markdown on boot, handle optional watcher (`WATCH=true`), and execute server as PID 1 (`exec node server.js`).
|
||||
Reference in New Issue
Block a user