verify-docs

# Verify docs freshness Run the four checks below and produce a single report. Do NOT auto-fix — surface findings for human review (stale docs usually need a human to decide whether behavior is still accurate). ## 1. Stale `last_verified` stamps Every canonical doc in this repo carries `<!-- last_verified: YYYY-MM-DD -->` near the top. - Glob: `README.md`, `ARCHITECTURE.md`, `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `docs/**/*.md`. - For each file, extract the stamp. Flag as **P1 stale** when: - Stamp is absent (canonical docs must have one), OR - Stamp is >60 days old, OR - Stamp date is earlier than the most recent commit touching the file's *owning module* per the Doc Update Mapping in `docs/dev-workflows.md`. Owning-module lookup (from `docs/dev-workflows.md`): | Doc | Owning module | |---|---| | `docs/features/pipeline.md` | `libs/core/genblaze_core/pipeline/` | | `docs/features/provider-system.md` | `libs/core/genblaze_core/providers/` | | `docs/features/media-embedding.md` | `libs/core/genblaze_core/media/` | | `docs/features/object-storage.md` | `libs/core/genblaze_core/storage/` + `libs/connectors/s3/` | | `docs/features/parquet-sink.md` | `libs/core/genblaze_core/sinks/` | | `docs/features/manifest-provenance.md` | `libs/core/genblaze_core/canonical/` + `libs/core/genblaze_core/models/manifest.py` | | `docs/features/cli.md` | `cli/` | | `ARCHITECTURE.md` | whole repo — use root mtime | | `docs/app-workflows.md` | `libs/core/` | | `docs/dev-workflows.md` | `Makefile` + `.github/workflows/` | Use `git log -1 --format=%cs -- <path>` to get last-touched date for a module. ## 2. Python example syntax Every Python fenced block in `docs/features/*.md` should at minimum be parseable. - For each code block (``` ```python ... ``` ```), write to a temp file and run `python3 -c "import ast; ast.parse(open(p).read())"`. - Report parse errors only. Ignore import-resolution failures (examples use real API keys that aren't available in the audit env). ## 3. Cross-reference link integrity - Grep markdown files for local links: `\[.+?\]\(\./.+?\)`, `\[.+?\]\(\.\./.+?\)`, `\[.+?\]\(docs/.+?\)`. - For each match, resolve relative to the link's source file. Flag unresolved. ## 4. Feature-doc ↔ canonical-file alignment `ARCHITECTURE.md` has a "Canonical Files" section mapping concepts to paths. Confirm each path listed there exists. Flag any `libs/core/genblaze_core/...` reference that no longer resolves (a common rot pattern after refactors). ## Report format ``` ## Docs Audit — YYYY-MM-DD ### P1 — Stale `last_verified` - docs/features/pipeline.md — stamp 2026-01-10, module last touched 2026-03-22 ### P2 — Broken example syntax - docs/features/webhooks.md — block 3: SyntaxError at line N ### P3 — Broken cross-links - README.md → docs/features/queue-integration.md: target not found ### P4 — Missing canonical file - ARCHITECTURE.md references libs/core/genblaze_core/old_module.py: not present ```