Page Health Audit¶

This audit checks tracked Markdown pages in docs/ that declare top-of-file metadata. In the current V2 rollout, that pilot covers the priority-lane dossiers plus the canonical event, daily, macro, and report pages that drive the live workflow.

What it checks¶

allowed page_type values: daily, dossier, event, report, operating-note
allowed status values: signal, monitor, active, stale, invalidated, archived
required fields for tracked pages: owner, last_reviewed, next_review, next_action, confidence, trigger, invalidation
allowed confidence values: low, medium, high
next_review dates that are already in the past for live pages

Pages without page_type metadata are ignored until they are enrolled into the pilot. Template files live under internal/templates/ and stay outside the published docs layer on purpose.

When to run it¶

after editing tracked research pages
after editing tracked daily pages
before publishing a batch of updates
when a page feels stale or incomplete
as part of a quick local health check from the project root

Run it like this:

source .venv/bin/activate
python tools/page_health_audit.py

To check only a few pages, pass them explicitly:

python tools/page_health_audit.py docs/companies/oracle.md docs/crypto/chainlink.md docs/macro/gold.md docs/reports/global-markets-now-2026-03-23.md

What to do with stale or incomplete pages¶

add the missing metadata before the page ships
if the thesis is still live, move next_review forward to a realistic date
if the page no longer matters, change the lifecycle state to archived or invalidated
closed pages can keep next_review empty or historical; live pages should still move it forward
if the page has drifted, update the body and the metadata together so the audit and the narrative stay aligned

The goal is not perfect paperwork. The goal is to keep live pages owned, reviewable, and easy to triage.