docs(research): v2.0 corrections for pointer_architecture_companion.m… #349
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # Documentation Quality Check | |
| # Validates documentation links, examples, and structure | |
| name: docs-check | |
| on: | |
| push: | |
| branches: [main, fix/*, feat/*] | |
| paths: | |
| - 'README.md' | |
| - 'docs/**.md' | |
| - 'CLAUDE.md' | |
| - 'AGENTS.md' | |
| - 'CONTRIBUTING.md' | |
| - '.github/workflows/docs-check.yml' | |
| pull_request: | |
| branches: [main] | |
| paths: | |
| - 'README.md' | |
| - 'docs/**.md' | |
| - 'CLAUDE.md' | |
| - 'AGENTS.md' | |
| - 'CONTRIBUTING.md' | |
| permissions: | |
| contents: read | |
| jobs: | |
| markdown-link-check: | |
| name: Check Documentation Links | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Link Checker | |
| uses: gaurav-nelson/github-action-markdown-link-check@v1 | |
| with: | |
| use-quiet-mode: 'yes' | |
| use-verbose-mode: 'yes' | |
| config-file: '.markdown-link-check.json' | |
| folder-path: 'docs' | |
| file-extension: '.md' | |
| check-modified-files-only: 'no' | |
| docs-structure: | |
| name: Validate Documentation Structure | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Check DOCUMENTATION_INDEX.md exists | |
| run: | | |
| if [ ! -f "docs/DOCUMENTATION_INDEX.md" ]; then | |
| echo "❌ DOCUMENTATION_INDEX.md not found" | |
| exit 1 | |
| fi | |
| echo "✅ DOCUMENTATION_INDEX.md exists" | |
| - name: Check key documentation files | |
| run: | | |
| for file in \ | |
| "README.md" \ | |
| "CLAUDE.md" \ | |
| "AGENTS.md" \ | |
| "CONTRIBUTING.md" \ | |
| "docs/ARCHITECTURE.md" \ | |
| "docs/command_registry.md" \ | |
| "docs/tri27/README.md" | |
| do | |
| if [ -f "$file" ]; then | |
| echo "✅ $file exists" | |
| else | |
| echo "❌ $file not found" | |
| exit 1 | |
| fi | |
| done | |
| - name: Check MEMORY.md size | |
| run: | | |
| MEMORY_FILE=".claude/projects/-Users-playra-trinity-w1/memory/MEMORY.md" | |
| if [ -f "$MEMORY_FILE" ]; then | |
| LINES=$(wc -l < "$MEMORY_FILE") | |
| echo "MEMORY.md: $LINES lines" | |
| if [ "$LINES" -gt 250 ]; then | |
| echo "⚠️ MEMORY.md is $LINES lines (should be <200)" | |
| echo "Consider moving content to topic files" | |
| else | |
| echo "✅ MEMORY.md size OK" | |
| fi | |
| fi | |
| command-examples: | |
| name: Validate README Command Examples | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Install Zig | |
| uses: goto-bus-stop/setup-zig@v2 | |
| with: | |
| version: 0.15.0 | |
| - name: Build tri CLI | |
| run: | | |
| zig build tri | |
| - name: Test basic commands from README | |
| run: | | |
| echo "Testing basic commands..." | |
| ./zig-out/bin/tri --version || true | |
| ./zig-out/bin/tri help || true | |
| ./zig-out/bin/tri constants || true | |
| echo "✅ Basic commands work" | |
| docs-index-updated: | |
| name: Check Documentation Index | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Check DOCUMENTATION_INDEX.md timestamp | |
| run: | | |
| if grep -q "Last updated: 2026-03-2[0-9]" docs/DOCUMENTATION_INDEX.md; then | |
| echo "✅ DOCUMENTATION_INDEX.md timestamp is current (March 2026)" | |
| else | |
| echo "⚠️ DOCUMENTATION_INDEX.md may need update" | |
| echo "Last updated date should be recent" | |
| fi | |
| - name: Check for broken section links | |
| run: | | |
| cd docs | |
| for section in $(grep -oP '(?<=^\[)[^\]]+(?=\])' DOCUMENTATION_INDEX.md 2>/dev/null | tr '[:upper:]' '[:lower:]'); do | |
| if grep -q "^## $section" *.md 2>/dev/null || \ | |
| grep -q "^## $section" DOCUMENTATION_INDEX.md 2>/dev/null; then | |
| echo "✅ Section: $section" | |
| else | |
| echo "⚠️ Section link may be broken: $section" | |
| fi | |
| done | |
| consistency-check: | |
| name: Documentation Consistency | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Check T-JEPA status consistency | |
| run: | | |
| echo "Checking T-JEPA implementation status across docs..." | |
| TJEPA_FILES="src/hslm/tjepa.zig src/hslm/tjepa_trainer.zig" | |
| for file in $TJEPA_FILES; do | |
| if [ -f "$file" ]; then | |
| echo "✅ $file exists (T-JEPA implemented)" | |
| else | |
| echo "❌ $file not found" | |
| exit 1 | |
| fi | |
| done | |
| echo "Note: If T-JEPA files exist, docs should reflect 'implemented' status" | |
| - name: Check version consistency | |
| run: | | |
| VERSION=$(grep -oP 'v\d+\.\d+\.\d+' README.md | head -1) | |
| if [ -n "$VERSION" ]; then | |
| echo "Found version: $VERSION" | |
| echo "✅ Version declared in README.md" | |
| else | |
| echo "⚠️ No version found in README.md" | |
| fi | |
| summary: | |
| name: Documentation Check Summary | |
| runs-on: ubuntu-latest | |
| needs: [markdown-link-check, docs-structure, command-examples, docs-index-updated, consistency-check] | |
| if: always() | |
| steps: | |
| - name: Summary | |
| run: | | |
| echo "# Documentation Check Summary" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| echo "| Job | Status |" >> $GITHUB_STEP_SUMMARY | |
| echo "|-----|--------|" >> $GITHUB_STEP_SUMMARY | |
| echo "| Link Check | ${{ needs.markdown-link-check.result }} |" >> $GITHUB_STEP_SUMMARY | |
| echo "| Structure | ${{ needs.docs-structure.result }} |" >> $GITHUB_STEP_SUMMARY | |
| echo "| Examples | ${{ needs.command-examples.result }} |" >> $GITHUB_STEP_SUMMARY | |
| echo "| Index | ${{ needs.docs-index-updated.result }} |" >> $GITHUB_STEP_SUMMARY | |
| echo "| Consistency | ${{ needs.consistency-check.result }} |" >> $GITHUB_STEP_SUMMARY |