Skip to content

v0.2.0 — beacon doctor health checks

Choose a tag to compare

View all tags
@Juliocbm Juliocbm released this 24 May 03:36
v0.2.0
b2a81c8

First minor release. New top-level command — beacon doctor — for soft health signals across the docs tree.

✨ New command: beacon doctor

Separate from lint by design:

  • lint answers "is the structure correct?" — hard rules (file naming, folder placement, AI-file sync). Fail PRs on violations.
  • doctor answers "is the docs tree healthy?" — soft signals (stale plans, ADRs stuck in proposed, evals not refreshed, backlog imbalance). Informational by default, opt into CI gating with --strict.
beacon doctor                # exit 0 even with findings (informational)
beacon doctor --strict       # exit 1 if any findings exist
beacon doctor --json         # machine-readable for tooling

Four initial checks across four areas

Area Check Triggers when...
Activity stale-plans a .plan.md is unmodified for ≥ 30 days
Decisions proposed-adrs an ADR has status: proposed for ≥ 14 days (uses frontmatter date, falls back to file mtime)
Snapshots old-evaluations an .eval.md is ≥ 6 months old AND no newer eval refreshes the same topic (substring slug match)
Balance backlog-balance active plans > 5 with empty backlog, OR plans:backlog ratio > 5:1

Output

Findings group by area, with file/folder glyphs and per-finding observation + suggestion:

◉ Activity (2)
  📄 docs/plans/shipping.plan.md
    └─ stale-plans: Last modified 47 days ago.
       → If shipped, run `beacon archive plan <slug>`. If stalled, add a status note.
  📄 docs/plans/refactor-auth.plan.md
    └─ stale-plans: Last modified 33 days ago.
       → ...

◇ Decisions (1)
  📄 docs/adr/ADR-007-event-bus.md
    └─ proposed-adrs: Stuck in "proposed" for 22 days.
       → Accept it, reject it, or update with a status note.

3 findings across 2 areas.

🧰 Internal

  • New module src/doctor/ parallel to src/linter/ — same walkDocs reused, distinct Check/Finding shape (no severity — uniform "info" level by design; strictness decided at the command level).
  • New module src/commands/doctor.ts orchestrates the 4 checks and formats output.
  • 73 new tests (147 → 220 passing across 37 files): 4 unit suites per check + runner suite + reporter suite + integration suite.
  • ADR-007 (beacon-doctor-design) captures the rationale; the implementation plan is now archived at docs/plans/_archive/v0-2-beacon-doctor.plan.md.

Install / upgrade

npm install -g beacon-docs@0.2.0
# or one-off:
npx beacon-docs@latest doctor

Full changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md

Assets 2
Loading