40 referenced-but-absent files across 19 repos — triaged (estate sweep)

[hyperpolymath]

An estate-wide sweep of 454 unique repos / 5,111 tracked shell scripts looked for literal file paths that scripts try to read (rg/grep/cat/source/[ -f ] operands) but which do not exist.

After discarding runtime-created files and vendored trees, 40 references across 19 repos remained. Triaged below — not all are defects, and the classes want different responses.

1. False positives — no action (5)

standards: a.md, b.md, x.md, target.md, check.sh — all inside scripts/spdx-inject-copyright-test.sh, which creates them as fixtures (cat > target.md <<EOF). Correctly absent from the repo.

2. Wrong path, not a missing licence (4)

repo	script looks for	repo actually has
anamnesis	LICENSE.txt	LICENSE + LICENSES/{AGPL-3.0-or-later,CC-BY-SA-4.0,MPL-2.0}.txt
my-lang	LICENSE.txt	LICENSE + LICENSES/{CC-BY-SA-4.0,MPL-2.0}.txt
social-media-polygraph	LICENSE-PALIMPSEST.txt	LICENSE + LICENSES/*
social-media-tools	LICENSE-PALIMPSEST.txt	LICENSE + LICENSES/PMPL-1.0-or-later.txt

The licences are present and correct; the checks name files that were never the convention. Repoint the checks at LICENSE / LICENSES/. These checks are failing today on compliant repos.

3. Genuine documentation gaps — the largest group (14)

An identical seven-file set is referenced but never authored, in two repos:

docs/API_REFERENCE.md   docs/ARCHITECTURE.md   docs/EXAMPLES.md   docs/FAQ.md
docs/MIGRATION.md       docs/QUICKSTART.md     docs/TROUBLESHOOTING.md

• asdf-tool-plugins — that set, plus RSR.md
• developer-ecosystem — that set, plus RSR.md, READINESS.md, TPCF.md

The identical shape in both suggests a scaffold that declared a documentation contract nobody then filled. Decision needed: author the docs, or drop the checks. Leaving them asserts a contract the repos do not meet.

4. Checks for banned tooling — stale by policy (3)

repo	looks for	note
preference-injector	deno.json	Deno is REMOVED estate-wide; Bun is the runtime
quandledb	frontend/deno.json	same
.git-private-farm	rescript.json	ReScript is purged estate-wide

These can never pass and should not — the tooling was deliberately removed. Delete the checks.

5. Possible undeclared dependencies (2)

candy-crash and universal-project-manager reference a package.json that does not exist. Worth checking against ubicity, where the same absence meant the project could not build under any toolchain — its sources imported zod and glob with no manifest declaring them (fixed in hyperpolymath/ubicity#107).

6. Same missing script in two repos (2)

bag-of-actions and continuation-mesh both reference guix-install.sh, absent from both. Likely a shared scaffold step that was never vendored in.

7. Singles (10)

repo	missing
academic-workflow-suite	run-tests.sh
excel-economic-numbers-tool	TPCF.md
lithoglyph	SUMMARY.md
protocol-squisher	docs/BENCHMARK-QUICKSTART.md
rsr-template-repo-experiment	scripts/check-no-vlang.sh
standards	scripts/apply-common-files.sh

Why this matters

A grep/rg on a missing file exits non-zero, so if ! rg … X; then fail; fi is permanently true — the check fails regardless of the repo's actual state. Where the reference sits inside if [ -f X ], the opposite happens: the guarded block is silently skipped and the gate reports success by not checking.

This sweep is the sibling of the .md→.adoc migration finding: 56 further checks across 18 repos were pointed at files the migration had renamed. Those are fixed (17 PRs). The 40 above are what remained after that class was removed.

Method note

The probe took four iterations before it was trustworthy: v1 examined 1 repo of 454 (a cd in a shared shell); v2 flagged 417 of 454 (it matched cross-repo uses: references); v3 flagged 57 but resolved paths only from the repo root, giving false positives on monorepo-relative and script-relative paths. v4 resolves from repo root, the script's own directory, or basename anywhere, and self-tests against a planted ghost file, a real file, a sibling-directory file and a cross-repo reference.

v3's 57 was the dangerous one — it sat squarely in the range a real defect rate would occupy, so nothing about the number itself would have caught it. Only opening three entries did.

[hyperpolymath]

⚠ Correction — group 3 was misclassified. The documentation is not missing.

I filed "3. Genuine documentation gaps — the largest group (14)" claiming docs/{API_REFERENCE,ARCHITECTURE,EXAMPLES,FAQ,MIGRATION,QUICKSTART,TROUBLESHOOTING}.md were never authored in asdf-tool-plugins and developer-ecosystem.

They exist. All of them, as .adoc, beside the script that checks for them:

asdf-ghjk/docs/
  API_REFERENCE.adoc  ARCHITECTURE.adoc  CITATIONS.adoc  COMPATIBILITY.adoc
  EXAMPLES.adoc  FAQ.adoc  MIGRATION.adoc  QUICKSTART.adoc  TROUBLESHOOTING.adoc

scripts/rsr-verify.sh checks for the .md names. This is the same .md → .adoc migration class as group 2 of this issue and as the 56 checks repointed across 18 repos earlier in the campaign — not a documentation gap at all.

Why my triage got it wrong

The detection probe resolved paths three ways (repo root, the script's own directory, basename anywhere). The classification step, which decided "migration gap" vs "genuinely missing", only looked for the .adoc twin at the repo root. These live at asdf-ghjk/docs/, so it found no twin and filed them as absent.

I fixed that root-relative flaw in the detector and never carried it into the classifier — the same bug surviving in the second half of the same tool.

Corrected totals

group	was	now
3. genuine documentation gaps	14	0
2. wrong path / migration class	4	18

The other groups stand: 5 false positives (standards test fixtures), 3 checks for banned tooling, 2 possible undeclared package.json dependencies, 2 × missing guix-install.sh, and the singles.

Fixed

• fix(rsr-verify): accept .adoc — the docs exist, the check named .md asdf-tool-plugins#71
• fix(rsr-verify): accept .adoc — the docs exist, the check named .md developer-ecosystem#194

Both accept either extension, matching the pattern the RSR template's own quality.yml already uses for README, LICENSE and CONTRIBUTING. Verified 7/7 checks satisfied against files on disk, 0 missing, shellcheck clean.

No documentation needed authoring. Had this not been checked first, 14 duplicate files would have been written in the wrong format alongside the correct ones.

[hyperpolymath]

Correction — group 4 ("checks for banned tooling") re-triaged

I proposed deleting three checks as stale. Having read how each is actually used, none of the three should simply be deleted, and one is a materially worse defect than filed.

1. preference-injector — the scorer penalises compliance ⚠

scripts/rsr-verify.sh awards RSR points like this:

category	points	requires
Type Safety — Bronze	80	deno.json with "strict": true
Type Safety — Silver	20	bsconfig.json (ReScript)
Memory Safety — Bronze	40	deno.json

The repo is written in AffineScript — 30 .affine files, the estate's endorsed language. It has no deno.json and no bsconfig.json, because both Deno and ReScript are banned estate-wide.

So the scorer grants points only for using two banned languages, and zero for the endorsed one actually in use. preference-injector scores 0/140 on these categories permanently — not for being non-compliant, but for being compliant.

This is not a stale check to delete; it is a scorer measuring the opposite of the policy. It needs new criteria, and the point values are a policy decision rather than a mechanical fix. Isolated — only this repo ships this scorer.

2. quandledb — an endorsed-language check gated behind a banned one

.claude/hooks/session-start.sh:134

if command -v deno && command -v affinescript && [ -f frontend/deno.json ]; then
  # type-check the AffineScript frontend

The AffineScript type-check only runs when Deno is installed and a deno.json exists. Neither is true, and neither should be. The check never runs — silently. Fix is to decouple it from Deno, not to delete it.

3. .git-private-farm — no action needed

scripts/bootstrap-hookset.sh:204 — if [ -f "rescript.json" ] || ls *.res inside a generated workflow. A properly guarded conditional that correctly does nothing when no ReScript is present. Working as intended.

Corrected totals

group	was	now
4. delete as stale	3	0
needs new criteria (policy)	—	1 (preference-injector)
needs decoupling	—	1 (quandledb)
working as intended	—	1 (.git-private-farm)

Related, found while triaging

30 repos still carry a live deno.json despite the standing ruling that Deno is removed estate-wide — including candy-crash/frontend, aerie/src/ui, burble/admin, avow-protocol, dicti0nary-attack, fireflag, dotmatrix-fileprinter, excel-economic-numbers-tool. Separately, candy-crash/scripts/check-languages.sh:125 advises "Should use deno.json" — a language-policy checker recommending a banned runtime. That advice is isolated to that one repo.

Group 5 also re-triaged — false positives

candy-crash and universal-project-manager both have zero JS sources and no npm imports; every package.json reference is conditional detection. Not the ubicity case. 0 defects, not 2.

[hyperpolymath]

Next step (spot-verified 2026-08-27, 10 of 40 entries across 6 classes — all 10 confirmed): the sweep is sound, with one correction: bag-of-actions does not exist as a repo in either org, so class 6 is 1 repo and the total is 18 repos, not 19.

→ Classes 2, 4, 6, 7 (~26 refs) are mechanical repointing/deletion — roughly one small PR per repo. Class 3 (the two 7-file doc sets, asdf-tool-plugins + developer-ecosystem, 0 of 7 present in each) is the one owner call inside this issue: author the docs or delete the contract.