Merge pull request #2 from bjcoombs/add-ci-guardrails

Add documentation guardrails CI

Author: franklywatson

.github/workflows/docs.yml

@@ -0,0 +1,157 @@
+name: Documentation Guardrails
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '**.md'
+      - '.markdownlint-cli2.jsonc'
+      - 'package.json'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - '**.md'
+      - '.markdownlint-cli2.jsonc'
+      - 'package.json'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  markdown-lint:
+    name: Markdown Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Run markdownlint
+        run: npm run lint:md
+
+  claude-md-line-limit:
+    name: CLAUDE.md Line Limit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check CLAUDE.md is under 150 lines
+        run: |
+          lines=$(wc -l < CLAUDE.md)
+          echo "CLAUDE.md: $lines lines"
+          if [ "$lines" -gt 150 ]; then
+            echo "::error::CLAUDE.md is $lines lines (limit: 150). Move content to linked docs."
+            exit 1
+          fi
+          echo "Within limit."
+
+  link-integrity:
+    name: Link Integrity
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check internal markdown links resolve
+        run: |
+          errors=0
+
+          # Find all markdown links in docs/
+          while IFS= read -r file; do
+            dir=$(dirname "$file")
+
+            # Extract markdown links: [text](path.md) and [text](path.md#anchor)
+            grep -oP '\[.*?\]\(\K[^)]+\.md(?:#[^)]*)?(?=\))' "$file" 2>/dev/null | while IFS= read -r link; do
+              # Strip anchor
+              target="${link%%#*}"
+
+              # Skip URLs
+              case "$target" in
+                http://*|https://*) continue ;;
+              esac
+
+              # Resolve relative path
+              resolved="$dir/$target"
+              if [ ! -f "$resolved" ]; then
+                echo "::error file=$file::Broken link: $link -> $resolved (file not found)"
+                # Write to a temp file since we're in a subshell
+                echo "1" >> /tmp/link_errors
+              fi
+            done
+          done < <(find . -name '*.md' -not -path './node_modules/*' -not -path './.git/*')
+
+          if [ -f /tmp/link_errors ]; then
+            count=$(wc -l < /tmp/link_errors)
+            echo "::error::$count broken link(s) found"
+            exit 1
+          fi
+          echo "All internal links resolve."
+
+  doc-reachability:
+    name: Doc Reachability from CLAUDE.md
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check all docs are reachable from CLAUDE.md
+        run: |
+          # Collect all markdown files in docs/
+          all_docs=$(find docs -name '*.md' | sort)
+
+          # Collect all files referenced from CLAUDE.md (@ syntax and markdown links)
+          referenced=$(grep -oP '(?:@|]\()\.?/?docs/[^)\s]+\.md' CLAUDE.md | sed 's/^@//' | sed 's/^](//' | sed 's/^(//' | sort -u)
+
+          orphans=0
+          for doc in $all_docs; do
+            # Normalize path (strip leading ./)
+            doc_clean="${doc#./}"
+            if ! echo "$referenced" | grep -qF "$doc_clean"; then
+              echo "::warning file=$doc_clean::Orphaned doc: $doc_clean is not referenced from CLAUDE.md"
+              orphans=$((orphans + 1))
+            fi
+          done
+
+          if [ "$orphans" -gt 0 ]; then
+            echo "$orphans orphaned doc(s) found. All docs should be reachable from CLAUDE.md."
+            echo "This is a warning, not a failure - add links to CLAUDE.md or delete orphaned files."
+          fi
+          echo "Reachability check complete."
+
+  writing-conventions:
+    name: Writing Conventions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check for filler words in docs
+        run: |
+          # CLAUDE.md writing rule: "No filler (basically, just, simply)"
+          warnings=0
+
+          while IFS= read -r file; do
+            # Skip code blocks by filtering out lines between ``` markers
+            # Check for filler words (case-insensitive, whole words only)
+            results=$(sed '/^```/,/^```/d' "$file" | grep -inP '\b(basically|simply)\b' || true)
+            if [ -n "$results" ]; then
+              while IFS= read -r match; do
+                echo "::warning file=$file::Filler word found: $match"
+                warnings=$((warnings + 1))
+              done <<< "$results"
+            fi
+          done < <(find docs -name '*.md')
+
+          if [ "$warnings" -gt 0 ]; then
+            echo "$warnings filler word(s) found. Per CLAUDE.md: 'No filler (basically, just, simply)'"
+            echo "This is a warning - review and remove where possible."
+          fi
+          echo "Writing conventions check complete."

.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+package-lock.json

.markdownlint-cli2.jsonc

@@ -0,0 +1,53 @@
+// markdownlint-cli2 configuration
+// Aligned with CLAUDE.md markdown conventions:
+//   Line length: Prefer 80-100, hard limit 120
+//   Headers: # for page title, ## for main sections, ### for subsections
+//   Code blocks: Specify language
+//   Lists: - for bullets, numbered for sequences
+//   No emoji in docs (exception: README.md sparingly)
+{
+  "config": {
+    "default": true,
+
+    // MD013/line-length
+    // CLAUDE.md says "prefer 80-100, hard limit 120" but existing prose
+    // exceeds 120 extensively. Disabled for now - enforce on new content
+    // by ratcheting down over time. Code blocks and headings are checked
+    // via other rules.
+    "MD013": false,
+
+    // MD024/no-duplicate-heading - allow in different sections
+    // Pattern docs reuse ### In Practice, ### Problem, ### Solution
+    "MD024": {
+      "siblings_only": true
+    },
+
+    // MD033/no-inline-html - allow for README badges and diagrams
+    "MD033": false,
+
+    // MD041/first-line-heading - disabled for files with front matter
+    "MD041": false,
+
+    // MD040/fenced-code-language - code blocks should specify language
+    // CLAUDE.md requires this but 42 existing blocks lack language tags
+    // (mostly directory structure diagrams). Disabled for now - enable
+    // after adding language tags to existing blocks (use `text` for
+    // directory trees and plain output).
+    "MD040": false,
+
+    // MD036/no-emphasis-as-heading - emphasis used as heading
+    // Pattern docs use **bold** for inline emphasis that isn't a heading
+    "MD036": false,
+
+    // MD051/link-fragments - false positives with anchor links
+    "MD051": false,
+
+    // MD060/table-column-style - table formatting is cosmetic
+    "MD060": false
+  },
+
+  "ignores": [
+    "**/node_modules/**",
+    "**/.git/**"
+  ]
+}

CLAUDE.md

@@ -32,20 +32,24 @@ See @README.md for detailed project overview.
 ## Writing Rules for This Repository
 
 **When writing docs:**
+
 - Language must be precise. No filler ("basically", "just", "simply").
 - No vague requirements ("make it fast", "clean it up").
 - Every claim must be specific and verifiable.
 
 **When writing examples:**
+
 - Working code only. No TODOs, no placeholders.
 - All examples must run as-is.
 - TypeScript and Python versions for each pattern.
 
 **Doc freshness:**
+
 - If you modify code in `examples/`, update the corresponding `docs/` file in the same session.
 - Code changes without doc updates are incomplete work.
 
 **Master index requirement:**
+
 - Every doc in this repo must be reachable from CLAUDE.md (this file).
 - This is the entry point — agents discover all project docs from here.
 
@@ -61,18 +65,23 @@ See @README.md for detailed project overview.
 ## Level Documentation
 
 **Foundation:**
+
 - @docs/L0-foundation.md — Deep modules, progressive disclosure, CLAUDE.md patterns
 
 **Closed Loop Design and Verification:**
+
 - @docs/L1-feedback-loops.md — Context harvesting, stack tests, full-loop assertions, sequential design
 
 **Behavioral Guardrails:**
+
 - @docs/L2-behavioral-guardrails.md — Skills, hooks, constitutional rules
 
 **Optimization:**
+
 - @docs/L3-optimization.md — Token efficiency, smart routing, guardrail middleware
 
 **Standards & Measurement:**
+
 - @docs/L4-standards-measurement.md — Evidence-based claims, drift detection, metrics
 
 ## Cross-Cutting Guides

README.md

@@ -73,6 +73,7 @@ docs/references/    # Case study and further reading
 ## Contributing
 
 This is a living pattern library. Contributions welcome:
+
 - **New patterns** that extend or challenge the existing framework
 - **Real-world examples** from different domains (the current examples lean toward ecommerce and trading)
 - **Corrections** when a pattern doesn't match your experience — document the exception