Adam Moussa
443297e8e4
Scheduled, read-only documentation gap detector. Diffs the org repo set + an optional read-only AWS inventory + the IT page-ID map (project_confluence_ migration) against Confluence and REPORTS doc gaps / stale pages / missing runbooks into the mode-600 report. RECOMMEND-ONLY per D3/D7: NEVER auto-writes Confluence; the on-demand SSH-invoked write path (incl. Mermaid edits via ~/.claude/scripts/confluence_mermaid.py) is a separate, gated provisioning path. LIVE Confluence API reads need the gated confluence-bot service-account token (D6); when creds are absent OR --no-api/--canary, the API checks are SKIPPED and noted, NEVER reported as a gap on missing data (mirrors compliance-drift's status-code-aware API-skip pattern: 200 parse, 404 real gap, else skip). Offline --canary asserts the doc-gap count (3) against a fixture (repo list + mock page-map + mock AWS inventory): a repo with no IT page, an AWS resource not in the map, and a missing required runbook page; precision non-gaps (matched repos/resources, doc-exempt repo, present required pages, skipped API) must not inflate the count. shellcheck-clean (only the shared SC1091 substrate-source info). PROVISIONING (confluence-bot account + 90-day rotation, page-1540098 live dry-run expecting 16 weweave macros, systemd wiring, coordinator registry) documented in the footer, deferred — gated.
2.5 KiB
confluence-doc canary fixtures
Planted doc-gap corpus for checkers/confluence-doc.sh --canary (offline, no network/token).
The checker asserts the total doc-gap count equals EXPECTED_GAP_COUNT (anti-complacency
floor, design §6.4). If a gap check regresses (stops firing) or the fixture changes, the count
drifts and the canary FAILS (exit 3).
--canary implies --dry-run + --no-api, so the LIVE Confluence API checks (page-existence +
staleness, which need the gated confluence-bot token, D6) are SKIPPED and noted — they are
never counted as a gap on missing data (memory feedback_cloudwatch_alarms).
Fixture inputs
| File | Role |
|---|---|
repos.txt |
the repo set to diff against the page-ID map (one repo name per line) |
mock-page-map.json |
a MOCK IT page-ID map (same shape as project_confluence_migration) |
mock-aws-inventory.json |
a MOCK read-only AWS inventory (what the API/collector would return) |
The 3 planted gaps
| Check | Subject | Why it's a gap |
|---|---|---|
| repo-documented | orphan-tool-repo |
no page in the mock map (and not doc-exempt) |
| aws-documented | afi-backup-monitor (Lambda) |
inventory resource with no page in the mock map |
| required-page | IAM & Access Management |
a REQUIRED standing page omitted from the mock map |
Non-gaps proving the checks are precise (must NOT inflate the count):
payments-dashboard,seahaven-slack-botrepos → matched to their pages.engineering-handbookrepo →DOC_EXEMPT_REPOS→ skipped, not a gap.payments-dashboardLambda → matched to the "Payments Dashboard" page.Incident Response Runbooks,Backup & Disaster Recoveryrequired pages → present in the map.- The LIVE API staleness/existence check → SKIPPED (no creds in canary), noted, not a gap.
Total = 3 (EXPECTED_GAP_COUNT).
When you add/remove a check, a fixture input, or a planted gap, update the fixture(s) and
EXPECTED_GAP_COUNT in the same commit (the canary edit is itself caught on the next run —
design §6.4).
Not exercised offline (PROVISIONING — gated)
The LIVE Confluence reads (and the on-demand WRITE path via
~/.claude/scripts/confluence_mermaid.py, including the page-1540098 live dry-run that must list
all 16 weweave Mermaid macros) require the confluence-bot service account + token. That account
creation, its 90-day rotation, and the Mermaid live dry-run are provisioning steps documented in
the checker's PROVISIONING footer — they are NOT performed by the canary.