Step 0+1: dual-purpose ADR + doc alignment + index.json regen + freshness CI#4
Merged
Conversation
Resolves the conflicting identities advertised across README/EXPLAINME/ TOPOLOGY by accepting that the repo serves two purposes and documenting the split. Closes #2 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Per ADR-0001 (repo purpose) the repository serves two explicit purposes: flat-file scan/drift data store, and ABI dogfood for the hyperpolymath Idris2 + Zig standard. The three top-level docs each described a different subset of this; bringing them into agreement. - README.adoc — rewritten with explicit two-purpose intro, a layout-by-purpose table, a Related-repos cross-link to verisimiser, and an index-freshness pointer (the CI lane added in a sibling commit). Preserves the existing scan ingest workflow + JSON format documentation under Purpose 1. - EXPLAINME.adoc — quote at top reflects both purposes; file map expanded to call out which subtrees serve which purpose; pointer to verisimiser added. - TOPOLOGY.md — Purpose section restated; module map updated to reflect the actual directory layout (no `hardware/` or `drift/` dirs — those were placeholders in the old doc); ffi/zig/ called out; integration points include verisimiser. Closes #2 (V-L1-J1 implementation; the ADR was the decision). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The committed index.json was stale: total_scans=301 (correct) but repos=["nafa-app","outreach","playbooks","project-cb","v-ecosystem"] (5 entries when there are 301 on disk), last_updated=2026-03-07 (two months stale at time of regen). Changes: - scripts/regen-index.sh — deterministic regen from scans/ on disk. last_updated derived from `git log -1 --format=%cI -- scans` so running it twice produces byte-identical output. Schema preserved (last_updated/total_scans/total_repos/repos); subdirectories under scans/ (e.g. scans/octads/) are intentionally not counted in total_scans — they are a separate space; if they need their own index, that is a follow-up. - index.json — regenerated. 301 scans, 301 repos (one repo per top-level file), last_updated=2026-03-28T08:28:32+00:00 (commit time of the most recent scans/ change). - .github/workflows/index-freshness.yml — runs regen-index.sh on push/PR and fails if index.json drifts from scans/. Triggers only on changes to scans/, index.json, the regen script, or the workflow itself. Pair with branch protection so the check is required for merge. Verified locally: - bash scripts/regen-index.sh produces a clean tree on second run (`git diff --quiet index.json` passes). Closes #1 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ground-clearing pass that resolves both issues filed against this repo (V-L3-M1 + V-L1-J1).
2 commits, each scoped to one logical change.
What changes
ADR + dual-purpose alignment (V-L1-J1)
docs/decisions/ADR-0001-repo-purpose.adoc— records that the repo serves two explicit purposes: (1) flat-file data store for panic-attacker scan output + drift snapshots; (2) ABI dogfood site for the hyperpolymath Idris2 + Zig ABI. Both stay; neither is moved out.README.adocrewritten around the two-purpose framing with a layout-by-purpose table and a Related-repos link toverisimiser.EXPLAINME.adocquote updated; file map expanded to call out which subtrees serve which purpose.TOPOLOGY.mdpurpose section + module map rewritten to reflect the actual directory layout (nohardware/, nodrift/— those were placeholders).Closes #2.
Index regen + freshness CI (V-L3-M1)
scripts/regen-index.sh— deterministic regen ofindex.jsonfromscans/on disk.last_updatedis derived fromgit log -1 --format=%cI -- scans/so consecutive runs produce byte-identical output. Subdirectories underscans/(e.g.scans/octads/) are intentionally not counted intotal_scans— they are a separate space.index.jsonregenerated. The committed version was stale: it claimed 5 repos with 301 scans (impossible) andlast_updated: 2026-03-07. New version: 301 scans, 301 repos (one per top-level file),last_updated: 2026-03-28T08:28:32+00:00..github/workflows/index-freshness.yml— runsregen-index.shon push/PR and fails if the committed index drifts fromscans/. Triggers only on changes toscans/,index.json, the regen script, or the workflow itself. Concurrency cancellation included.Closes #1.
Test plan
bash scripts/regen-index.shon a clean tree produces no diff (deterministic)index.jsonnow lists all 301 repos in sorted orderindex.json freshnesslane green on pushscans/*.jsonchange lands without anindex.jsonregen (verify post-merge by deliberately editing one file)scans/🤖 Generated with Claude Code