Skip to content

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

Open
Open
40 referenced-but-absent files across 19 repos — triaged (estate sweep)#653
Labels
priority:p2Normal - queue itscope:estateAffects many or all repos across the estatestatus:readyFully specified and ready to be picked uptech-debtKnown shortcut, drift, or hygiene owed - includes cleanup

Description

@hyperpolymath
hyperpolymath
opened on Aug 26, 2026

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.

Activity

  1. hyperpolymath commented on Aug 26, 2026

    @hyperpolymath
    hyperpolymath
    on Aug 26, 2026
    OwnerAuthor

    ⚠ 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

    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.

  2. hyperpolymath commented on Aug 26, 2026

    @hyperpolymath
    hyperpolymath
    on Aug 26, 2026
    OwnerAuthor

    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.

  3. hyperpolymath
    added
    scope:estateAffects many or all repos across the estate
    tech-debtKnown shortcut, drift, or hygiene owed - includes cleanup
    on Aug 27, 2026

  4. hyperpolymath commented on Aug 27, 2026

    @hyperpolymath
    hyperpolymath
    on Aug 27, 2026
    OwnerAuthor

    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.

  5. hyperpolymath commented on Aug 31, 2026

    @hyperpolymath
    hyperpolymath
    on Aug 31, 2026
    OwnerAuthor

    Re-measured 2026-08-31 on today's main: 0 of the 40 refs are fixed. Three corrections to the thread:

    1. bag-of-actions was renamed to continuation-mesh (the API redirects) — it exists; the earlier triage note recording it as nonexistent is wrong. Net: 39 distinct refs across 18 repos, and a stale duplicate checkout of the old name remains on disk (recorded on Duplicate checkout trees double-count every estate census — repos/ vs hyper-repos/ overlap on 213 names, _SET containers hold 412 nested repos #703).
    2. The "Fixed" note above is premature: asdf-tool-plugins#71 and developer-ecosystem#194 are both still OPEN — both repos' rsr-verify.sh on main still run .md-only doc checks while the .adoc twins sit in docs/.
    3. excel-economic-numbers-tool now has docs/governance/TPCF.md, but scripts/verify-rsr.sh still checks root TPCF.md — moved from the missing-file class to the wrong-path class (check fails on a compliant repo).

    Actionable scope after this thread's own re-triage (fixtures and non-defects excluded): 31 refs / 15 repos. Stays open as REAL WORK at that scope.

  6. hyperpolymath
    added 2 commits that reference this issue on Sep 2, 2026

    fix(rsr-verify): accept .adoc — the docs exist, the check named .md (#…

    34842da

    fix(compliance): point the Palimpsest check at LICENSES/PMPL-1.0-or-l…

    cb44536
  7. hyperpolymath
    added 2 commits that reference this issue on Sep 14, 2026

    fix(rsr-verify): score the endorsed stack, not four banned ones (#80)

    70b94c0

    fix(rsr-verify): accept .adoc — the docs exist, the check named .md (#71

    4a828f6
  8. hyperpolymath
    added
    priority:p2Normal - queue it
    status:readyFully specified and ready to be picked up
    on Sep 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:p2Normal - queue itscope:estateAffects many or all repos across the estatestatus:readyFully specified and ready to be picked uptech-debtKnown shortcut, drift, or hygiene owed - includes cleanup

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions