feat: add doctest tool and Bats harness for Markdown code blocks

[trevor-vaughan]

Go tool (cmd/doctest/) uses goldmark to parse fenced code blocks
annotated with {test="..."} from Markdown files. Bats test harness
runs extracted snippets. Motivated by 11 open issues where Getting
Started page commands were broken or untested.

• Add cmd/doctest/ with extract and coverage subcommands
• Add Bats test harness via npm (bats-core, bats-support, bats-assert)
• Add Makefile targets: test-docs-extract, test-docs, test-docs-coverage
• Wire doc tests into CI (informational, non-blocking until blocks are annotated)
• Add spec and plan in specs/015-testable-documentation/
• Update CONTRIBUTING.md and README.md; create AGENTS.md

Details:

Go tool (cmd/doctest/):

• goldmark AST parser extracts annotated fenced code blocks to disk
• coverage subcommand exits non-zero when untested executable blocks exist
• Table-driven unit tests cover parsing, extraction, slug derivation, and coverage

Bats harness (tests/docs/):

• Installed as npm devDependencies (project already uses npm for Hugo)
• Helper scripts wrap snippet execution; skeleton test for getting-started guide

Build and CI:

• DOCTEST_DIR variable decouples extract output path from test input path
• Go tests run before doc tests so coverage failures don't block unit tests
• Doc test step uses || true until remaining blocks are annotated
• .gitignore: .test-output/, doctest binary, cmd/sync-content/sync-content

Assisted-by: Claude Opus 4.6
Signed-off-by: Trevor Vaughan tvaughan@redhat.com

[github-actions]

✅ CRAP Load Analysis: PASS (no baseline)

No baseline file found at .gaze/baseline.json. Showing current scores without regression detection.

How to Enable Regression Detection

Generate and commit a baseline file to track CRAP score changes over time:

# 1. Install gaze
go install github.com/unbound-force/gaze/cmd/gaze@latest

# 2. Run tests and generate baseline
go test -coverprofile=coverage.out ./...
mkdir -p .gaze
gaze crap --format=json --coverprofile=coverage.out ./... > .gaze/baseline.json

# 3. Commit the baseline
git add .gaze/baseline.json
git commit -m "chore: add CRAP baseline for regression detection"

For more information:

• Gaze README
• CI Integration Guide

Summary

Metric	Value
Functions analysed	12
Avg complexity	8.3
Avg line coverage	74.8%
Avg CRAP score	19
CRAPload (>= 15)	3
Avg contract coverage	0%
Avg GazeCRAP score	0
GazeCRAPload (>= 15)	0

View full analysis logs