Standing reachability audit: half-built features are invisible to trackers #515

Closed
opened 2026-10-27 13:36:37 +00:00 by sam · 0 comments
Owner

Trackers record INTENTION ("build a cron job store"); nothing records COMPLETION STATE ("cronstore is 2009 lines of that intention, executing nowhere"). A package can be planned, partially built, and unreachable, and no tracker shows it. This epic makes that dimension standing and queryable.

Evidence

The first audit (2026-09-12, deadcode over ./... cross-referenced with go list -deps ./cmd/...) found 10326 lines across 13 packages in no shipped binary:

package LOC tracked
ratelimit 494 NONE
servicediscovery (contract) 163 NONE
cronstore 2009 #270
memory/scrubber 1362 #630 (adjacent)
domain/scheduling 1323 #270/#676
pairing 1103 #248
servicediscovery/nats 1067 weak/none
configuration/setup 917 #368/#72
domain/sampling 540 #437
configuration/tomlwrite 526 #368
domain/image 438 image epic
terminalprompt 384 #368

Two had no tracker item at all and are now filed (archie-core-6wxb ratelimit, archie-core-53jc servicediscovery). The rest are TRACKED-but-unreachable: legitimately incomplete features, correctly planned, whose only defect is that their completion state is not visible anywhere.

Dates cluster: sampling, servicediscovery/* and domain/image all landed 2026-09-02..09-05, during the service-decomposition push. Not scattered neglect -- a build-out burst whose wiring was deferred.

Deliverable

A generator that reports, for every package and exported symbol:

  • reachability (in the cmd closure or not)
  • consumer count (importers outside its own package, excluding tests)
  • provenance (first added, last touched, by commit)
  • tracker status (does an open issue/bead cover it)

so "is it implemented?" and "is it reachable?" are separate, answerable questions rather than requiring manual archaeology. It must treat tracker coverage as an INPUT, not a conclusion: tracked-and-unreachable is a status, not a bug.

Why not just deadcode

deadcode alone produced 287 findings that read as a cleanup list. Cross-referencing with git, the cmd dependency closure and the trackers converts that into three distinct categories -- genuinely dead, tracked-incomplete, and invisible-to-static-analysis (Yaegi, 29 packages) -- which have entirely different actions.

Acceptance

  • Generator runnable on demand, output written where it can be read.
  • Every unreachable package appears with its tracker status.
  • Yaegi/reflection blind spots are labelled, never silently included as dead.
  • Findings are never auto-deleted; the report is advisory.

Close reason

Epic delivered: tools/reachaudit/reachaudit.py (reachability + consumer/provenance + tracker-status classification, dynamic blind spots labelled, advisory) and tools/contractaudit, both runnable via Taskfile tasks; all four acceptance criteria met


Imported from beads archie-core-06ag · GitHub #796 · type epic · priority P1 · created 2026-09-12 · closed 2026-09-18

Trackers record INTENTION ("build a cron job store"); nothing records COMPLETION STATE ("cronstore is 2009 lines of that intention, executing nowhere"). A package can be planned, partially built, and unreachable, and no tracker shows it. This epic makes that dimension standing and queryable. ## Evidence The first audit (2026-09-12, deadcode over ./... cross-referenced with `go list -deps ./cmd/...`) found 10326 lines across 13 packages in no shipped binary: package LOC tracked ratelimit 494 NONE servicediscovery (contract) 163 NONE cronstore 2009 #270 memory/scrubber 1362 #630 (adjacent) domain/scheduling 1323 #270/#676 pairing 1103 #248 servicediscovery/nats 1067 weak/none configuration/setup 917 #368/#72 domain/sampling 540 #437 configuration/tomlwrite 526 #368 domain/image 438 image epic terminalprompt 384 #368 Two had no tracker item at all and are now filed (archie-core-6wxb ratelimit, archie-core-53jc servicediscovery). The rest are TRACKED-but-unreachable: legitimately incomplete features, correctly planned, whose only defect is that their completion state is not visible anywhere. Dates cluster: sampling, servicediscovery/* and domain/image all landed 2026-09-02..09-05, during the service-decomposition push. Not scattered neglect -- a build-out burst whose wiring was deferred. ## Deliverable A generator that reports, for every package and exported symbol: - reachability (in the cmd closure or not) - consumer count (importers outside its own package, excluding tests) - provenance (first added, last touched, by commit) - tracker status (does an open issue/bead cover it) so "is it implemented?" and "is it reachable?" are separate, answerable questions rather than requiring manual archaeology. It must treat tracker coverage as an INPUT, not a conclusion: tracked-and-unreachable is a status, not a bug. ## Why not just deadcode deadcode alone produced 287 findings that read as a cleanup list. Cross-referencing with git, the cmd dependency closure and the trackers converts that into three distinct categories -- genuinely dead, tracked-incomplete, and invisible-to-static-analysis (Yaegi, 29 packages) -- which have entirely different actions. ## Acceptance - Generator runnable on demand, output written where it can be read. - Every unreachable package appears with its tracker status. - Yaegi/reflection blind spots are labelled, never silently included as dead. - Findings are never auto-deleted; the report is advisory. ### Close reason Epic delivered: tools/reachaudit/reachaudit.py (reachability + consumer/provenance + tracker-status classification, dynamic blind spots labelled, advisory) and tools/contractaudit, both runnable via Taskfile tasks; all four acceptance criteria met --- _Imported from beads `archie-core-06ag` · GitHub #796 · type epic · priority P1 · created 2026-09-12 · closed 2026-09-18_
sam added the highepic labels 2026-10-27 13:36:37 +00:00
sam self-assigned this 2026-10-27 13:36:37 +00:00
sam closed this issue 2026-10-27 13:36:37 +00:00
sam added a new dependency 2026-10-27 13:42:14 +00:00
sam added a new dependency 2026-10-27 13:42:24 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#515