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
@@ -65,6 +65,7 @@
|
||||
excerpt: "Single paragraph summary"
|
||||
readingTime: "X MIN READ"
|
||||
draft: false
|
||||
hidden: false # optional: true unlists post from public feeds/lists, accessible via direct link only
|
||||
```
|
||||
2. **Obsidian Normalization:**
|
||||
- Wikilinks `[[slug]]` or `[[slug|Label]]` must be transformed into standard web URLs (`/posts/slug/`).
|
||||
|
||||
@@ -61,7 +61,8 @@ This skill guides the agent in implementing the custom Obsidian plugin and serve
|
||||
## 3. Obsidian Markdown Normalization Rules
|
||||
|
||||
1. **Frontmatter Invariants:**
|
||||
- Must contain `title`, `date`, `tags` (array), and optional `excerpt`, `readingTime`, `draft`.
|
||||
- Must contain `title`, `date`, `tags` (array), and optional `excerpt`, `readingTime`, `draft`, `hidden`.
|
||||
|
||||
2. **Wikilinks Translation:**
|
||||
- `[[article-slug]]` $\rightarrow$ `[article-slug](/posts/article-slug/)`
|
||||
- `[[article-slug|Custom Label]]` $\rightarrow$ `[Custom Label](/posts/article-slug/)`
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
name: standards-verification
|
||||
description: >-
|
||||
Use this skill sparingly when a new major function or feature has been implemented, when the user explicitly asks to verify standards, or as a debugging tool to analyze code issues. Targets only modified or relevant files via git status/diff and evaluates them against the project standards document.
|
||||
---
|
||||
|
||||
# Standards Verification Skill
|
||||
|
||||
This skill performs targeted architectural and stylistic compliance verification for new or modified code in this repository.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Invocation Policy:** Call this skill **sparingly and only when needed**.
|
||||
> **Valid Triggers:**
|
||||
> 1. A new major function or architectural feature has been implemented.
|
||||
> 2. The user asks to call it or requests standards verification.
|
||||
> 3. An error, test failure, or regression has occurred, and you are using this skill as a debugging tool to determine where the code diverges from project standards.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 1. Targeted Inspection Scope (Not the Whole Codebase)
|
||||
|
||||
Do **NOT** scan or audit the whole codebase unless specifically requested by the user or strictly necessary for whole-system refactors.
|
||||
|
||||
Instead, narrow the scope to targeted sections using Git:
|
||||
|
||||
1. **Check Modified Files:**
|
||||
```bash
|
||||
git status -s
|
||||
```
|
||||
2. **Inspect Exact Changes:**
|
||||
```bash
|
||||
git diff HEAD
|
||||
```
|
||||
Or for staged changes:
|
||||
```bash
|
||||
git diff --staged
|
||||
```
|
||||
3. **Identify Changed Sections:**
|
||||
Focus only on the files, functions, templates, or styles touched in the current task.
|
||||
|
||||
---
|
||||
|
||||
## 2. Standards Evaluation Workflow
|
||||
|
||||
To verify compliance, read the dedicated project standards document:
|
||||
- Authoritative document: [`.agents/standards.md`](file:///home/venus/code/blog/.agents/standards.md) (or local skill reference: [`references/standards.md`](file:///home/venus/code/blog/.agents/skills/standards-verification/references/standards.md)).
|
||||
|
||||
Evaluate the targeted changes against the core standard pillars:
|
||||
|
||||
1. **Design System & CSS Rules:**
|
||||
- Are any anti-patterns present? Check for `backdrop-filter`, `box-shadow`, `text-shadow` (other than `none`), gradients, or transitions with delays/curves.
|
||||
- Are border radii strictly bounded between `0px` and `4px`?
|
||||
- Are colors utilizing CSS custom properties from `tokens.css`?
|
||||
- Is styling modularized without inline `<style>` tags?
|
||||
|
||||
2. **Templating & Eleventy Architecture:**
|
||||
- Does post rendering adhere to layout inheritance (`base.njk` -> `post.njk`)?
|
||||
- Are collections (`posts`, `tagList`) properly filtered using `isPostPublic`?
|
||||
- If a post is marked `hidden`, does the layout emit `<meta name="robots" content="noindex, nofollow">`?
|
||||
|
||||
3. **Content & Frontmatter Contracts:**
|
||||
- Are required frontmatter keys (`title`, `date`, `tags`, `excerpt`) valid and conforming to schema length invariants?
|
||||
- Are wikilinks and Obsidian attachments normalized?
|
||||
|
||||
4. **Server & Security Invariants:**
|
||||
- Does `server.js` preserve security headers (`X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`)?
|
||||
- Is path traversal protection in place for all file-serving and API endpoints?
|
||||
|
||||
5. **Test-Driven Development (TDD) Invariants:**
|
||||
- Were automated test cases written *before* functional code was modified?
|
||||
- Are adversarial test cases included (boundary inputs, nulls, invalid configs)?
|
||||
- Do all tests pass (`npm test`)?
|
||||
|
||||
---
|
||||
|
||||
## 3. Stylistic & Architectural Reporting
|
||||
|
||||
Compile a structured report highlighting:
|
||||
- **Conformant Highlights:** Key standards cleanly satisfied.
|
||||
- **Stylistic Issues & Deviations:** Any formatting inconsistencies, unneeded inline styles, or naming anomalies.
|
||||
- **Remediation Steps:** Concrete, minimal code adjustments to bring the implementation into full compliance.
|
||||
|
||||
---
|
||||
|
||||
## 4. Debugging with Standards Verification
|
||||
|
||||
When using this skill as a debugging tool to troubleshoot broken builds, failed tests, or runtime bugs:
|
||||
|
||||
1. **Locate the Error:** Inspect test failure outputs or server logs to isolate the failing component.
|
||||
2. **Correlate with Standards:** Compare the problematic implementation against [`.agents/standards.md`](file:///home/venus/code/blog/.agents/standards.md).
|
||||
3. **Explain the Discrepancy:** Specifically identify where the code is out of touch with project standards (e.g. missing input guards for `null`, collections bypassing `isPostPublic`, un-sanitized slug paths).
|
||||
4. **Suggest Root Cause & Fix:** Suggest why those issues cause an error and provide the targeted fix.
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# 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]]` -> ``.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,76 @@
|
||||
#!/usr/bin/env node
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { execSync } from "node:child_process";
|
||||
|
||||
console.log("\n[Standards Verification] Running targeted inspection on modified files...\n");
|
||||
|
||||
let statusOutput = "";
|
||||
try {
|
||||
statusOutput = execSync("git status -s", { encoding: "utf-8" }).trim();
|
||||
} catch (err) {
|
||||
console.error("Error executing git status:", err.message);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (!statusOutput) {
|
||||
console.log("✔ Working tree is clean. No changed files to inspect.");
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
const lines = statusOutput.split("\n");
|
||||
const modifiedFiles = lines
|
||||
.map((line) => line.slice(3).trim())
|
||||
.filter((f) => fs.existsSync(f) && fs.statSync(f).isFile());
|
||||
|
||||
console.log(`Targeting ${modifiedFiles.length} modified file(s):`);
|
||||
modifiedFiles.forEach((f) => console.log(` - ${f}`));
|
||||
console.log("");
|
||||
|
||||
let issuesFound = 0;
|
||||
|
||||
for (const file of modifiedFiles) {
|
||||
const content = fs.readFileSync(file, "utf-8");
|
||||
|
||||
// 1. CSS anti-patterns
|
||||
if (file.endsWith(".css")) {
|
||||
if (/backdrop-filter\s*:/i.test(content)) {
|
||||
console.error(`✖ Violation in ${file}: Glassmorphism (backdrop-filter) is strictly forbidden.`);
|
||||
issuesFound++;
|
||||
}
|
||||
const shadowMatches = content.match(/(box-shadow|text-shadow)\s*:\s*([^;]+);/gi) || [];
|
||||
for (const match of shadowMatches) {
|
||||
if (!/(box-shadow|text-shadow)\s*:\s*none\s*;/i.test(match)) {
|
||||
console.error(`✖ Violation in ${file}: Drop shadows/glows forbidden: '${match}'`);
|
||||
issuesFound++;
|
||||
}
|
||||
}
|
||||
if (/(linear-gradient|radial-gradient|conic-gradient)/i.test(content)) {
|
||||
console.error(`✖ Violation in ${file}: Gradients are strictly forbidden.`);
|
||||
issuesFound++;
|
||||
}
|
||||
const radiusMatches = content.match(/border-radius\s*:\s*([^;]+);/gi) || [];
|
||||
for (const match of radiusMatches) {
|
||||
const pxMatch = match.match(/(\d+)\s*px/i);
|
||||
if (pxMatch && parseInt(pxMatch[1], 10) > 4) {
|
||||
console.error(`✖ Violation in ${file}: Border radius must be <= 4px: '${match}'`);
|
||||
issuesFound++;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Monolithic inline styles in templates
|
||||
if (file.endsWith(".njk") || file.endsWith(".html")) {
|
||||
if (/<style[^>]*>[\s\S]*?<\/style>/i.test(content)) {
|
||||
console.error(`✖ Violation in ${file}: Monolithic inline <style> tags are forbidden. Modularize into src/assets/css/`);
|
||||
issuesFound++;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (issuesFound > 0) {
|
||||
console.error(`\n✖ Standards Verification failed: ${issuesFound} issue(s) detected.\n`);
|
||||
process.exit(1);
|
||||
} else {
|
||||
console.log("✔ Targeted standards verification passed with 0 violations.\n");
|
||||
}
|
||||
@@ -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