Skip to main content

Spec Coverage Ledger

Every feature in AiMOneHealth is supposed to ship with a matching specs/NNN-*/ folder containing three files: spec.md, plan.md, tasks.md. The speckit pipeline enforces this when /speckit.* slash-commands are used interactively. Agent-authored code that bypasses the slash commands can drift behind the 3-file contract.

This page is the living record of the 2026-04-24 spec-coverage audit + the catchup effort that closes the gaps it surfaced.

2026-04-24 audit — headline​

  • Total specs: 64
  • With full 3-file coverage: 55 (86%)
  • Shipped-without-spec gaps: 0 — every module in apps/, packages/, scripts/, infrastructure/ traces to a specs/NNN-*/spec.md
  • Shipped-without-tasks gaps: 5 (specs 017, 018, 057, 063, 064)
  • Draft-without-plan gaps: 3 (specs 004, 005, 024)

Full report: spec-coverage-audit-2026-04-24T091518Z.md.

2026-04-26 verification — post push-forward run​

After the 42-PR Spec 066 + BAA-approval push-forward run (#259–#299):

  • Total specs: 66 (+2 since 2026-04-24 — 064-numeric-freshness-scorer-phase-3-ui plan-only follow-up, 066-reasoning-flow-tracker extended through Phase 4b.2-b + the entire self-improvement loop arc).
  • Shipped-without-tasks gaps: 5 — unchanged. Specs 017, 018, 057, 063, 064 still missing tasks.md. Catchup Phase 2 remains pending; not blocked by the 042526 work.
  • Draft-without-plan gaps: 3 — unchanged.
  • Spec 066 coverage: full 3-file plus extras (analyze.md, hipaa-review.md, ux-review.md, phase-4-preflight.md). The self-improvement loop arc (#259–#298) extended Phase 1c → Phase 4b.2-b implementation under the existing spec without needing a new specs/NNN-*/ folder, which is correct per the spec-amendment policy (FR additions to an existing spec land in that spec's spec.md).

The catchup ledger phase counts below reflect 2026-04-24 state; phases 2-5 will track in their respective backfill PRs.

Catchup ledger​

The CatchupDocumentation/ folder at the repo root is the rollup artifact carrying the catchup's own requirements.md + spec.md + plan.md + tasks.md. It exists outside the specs/NNN-*/ tree because it spans multiple specs.

Five phases:

PhaseScopeTarget
1 — LedgerCatchup folder + 4 artifacts authored✅ done
2 — Shipped-without-tasks backfill5 PRs, one per target spec (017, 018, 057, 063, 064)2026-05-01
3 — Draft-spec decisionsPlans for 004 + 005 (blocked on spec 002); archive-or-promote call for 0242026-05-05
4 — Testing + CI gatescripts/spec-coverage-check.mjs fail-closed gate + testing plan doc2026-05-08
5 — Docs siteThis page + sidebar entry + live status table✅ in progress

Shipped-without-tasks specs​

Each target gets a single backfill PR that lands specs/NNN-*/tasks.md citing:

  • PR number(s) where the code shipped
  • Primary files the T-number produced
  • Test(s) that exercise the T-number

Draft-without-plan specs​

SpecStatusBlockerTarget action
004 — MFA OnboardingDraftParent spec 002 (MFA) still in flightAuthor plan within 2 weeks of 002 merge
005 — MFA UpdateDraftSame as 004Same as 004
024 — Knowledge Infra AlignmentDraftResearch-only; needs archive-or-promote callSolo-maintainer decision by 2026-05-05

Why this happened​

The audit identified three contributing factors:

  1. Agent-authored code skips /speckit.tasks — the harness-level hook fires only on interactive /speckit.* invocations. A subagent writing files directly creates no tasks.md entry.
  2. pattern-consistency + docs-coverage gates catch pattern + doc drift, but not file-count drift — they don't fail a PR just because a spec folder has 2 files instead of 3.
  3. No CI-level spec-coverage-check — the 3-file invariant is not actively enforced at merge time.

Phase 4 of the catchup adds the enforcement layer: a new scripts/spec-coverage-check.mjs gate that refuses merge when a PR ships code under a specs/NNN-*/ folder missing tasks.md (with a respect-archived-manifest bypass for legacy specs).

How this is kept current​

  • Quarterly re-audit: re-run the 2026-04-24 audit prompt against main; report lands in .claude/reports/ with the same filename pattern.
  • Per-PR gate (Phase 4): spec-coverage-check becomes a mandatory merge gate; any regression fails the PR at CI time.
  • Ledger update cadence: this page is regenerated from CatchupDocumentation/tasks.md + the quarterly audit report. Backfills as they land drop the shipped-without-tasks count; Draft-spec decisions flip rows from blocked to done or archived.

Living status — 2026-04-24​

PhaseCountStatus
1 — Ledger5/5✅ authored
2 — Backfill PRs0/6🟡 pending
3 — Draft decisions0/3🟡 blocked on 002 + pending 024 call
4 — Testing + CI gate0/6📋 scheduled
5 — Docs surfacein progress🟢 this page

Re-check this page after each backfill lands — the count column is the live tracker.