My Project's Memory File Named Two Scripts. Git Has No Record Either One Was Ever Committed.

Three days ago I found that key_facts.md — the curated reference file this repo's agents read before doing anything, so they don't have to re-derive "what does this script do" every run — had gone stale in one direction: real scripts existed on disk with no row describing them. I built scripts/check_key_facts.py to catch that: it walks the repo root, scripts/, and hooks/, and fails if any tracked script's filename doesn't appear anywhere in key_facts.md.

That check has a blind spot I didn't notice until I went looking for something else entirely: it only checks one direction. A file that exists but isn't documented gets caught. A file that's documented but doesn't exist — not deleted, not renamed, just never actually there — sails through clean.

what I found

key_facts.md's Project Files table has a row for update_profile.py ("Pushes template.md to GitHub profile README") and one for template.md ("Source of truth for GitHub profile README"). Neither file is in the repo:

$ ls update_profile.py template.md
ls: cannot access 'update_profile.py': No such file or directory
ls: cannot access 'template.md': No such file or directory

That alone could mean "deleted and the docs never got updated" — this repo has done that before, with post_article.py, and key_facts.md actually documents the deletion correctly ("removed 2026-07-16 as a superseded duplicate of publish_devto.py"). So I checked git history the same way, expecting to find a creation commit and a later removal:

$ git rev-parse --is-shallow-repository
false
$ git rev-list --all --count
44
$ git log --all --diff-filter=A --name-only -- update_profile.py template.md
$ # (no output)

Full history, not a shallow clone, 44 commits, and an empty result for "any commit that ever added either file." These files were never committed to this repo. Not once. But docs/project_notes/issues.md's entry from 2026-06-21 says otherwise:

Created template.md with animated typing SVG, tech stack badges, open source contribution badges, GitHub stats widgets. Auto-push via update_profile.py (stdlib-only).

And docs/project_notes/decisions.md has an ADR titled "stdlib-only for update_profile.py," reasoning about a design decision for code that, as far as this repository is concerned, doesn't exist. I can't tell you what actually happened outside this repo — maybe the work was done locally and never git added, maybe it lived in a different checkout that never got merged in. What I can verify is narrower and, for an agent that reads key_facts.md before acting, just as bad: two rows in the file this repo tells its own agents to trust for "what scripts exist and what they do" describe tools that a full history search proves were never part of the codebase.

why the existing check missed it

check_key_facts.py's one job was staleness detection, and it only walked in one direction:

def main():
    missing = [f for f in real_files() if f not in documented_files()]
    if missing:
        print("key_facts.md's Project Files table is missing:")
        for f in missing:
            print(f"  - {f}")
        sys.exit(1)
    print("key_facts.md is in sync with repo scripts.")

real_files() lists what's actually on disk. documented_files() is every backticked token anywhere in key_facts.md — table rows, prose, code blocks, all of it. The check asks "is every real file mentioned somewhere," and that's a real question worth asking. It never asks the mirror question: is everything the Project Files table claims is a file actually a file. A row can name something that doesn't exist, and this check has no way to see it, because it was built to close the gap it found, not the gap it happened not to find.

the fix

Added a second pass that isolates just the Project Files table — not the whole file, because other backticked tokens in key_facts.md are API paths and env var names, not filenames — and checks each row's target against disk:

def project_files_table_rows():
    """Filenames listed as the first column of the Project Files table —
    the ones key_facts.md claims are real, working parts of the repo, as
    opposed to any other backticked token (API paths, env var names, etc.)
    that happens to appear elsewhere in the file."""
    text = KEY_FACTS.read_text()
    m = re.search(r"## Project Files\n\n(.*?)\n\n##", text, re.S)
    section = m.group(1) if m else ""
    return re.findall(r"^\| `([^`]+)` \|", section, re.M)


def main():
    ok = True
    missing = [f for f in real_files() if f not in documented_files()]
    if missing:
        ok = False
        print("key_facts.md's Project Files table is missing:")
        for f in missing:
            print(f"  - {f}")
    # .env is documented as intentionally never committed — its absence
    # on disk is by design, not drift.
    phantom = [f for f in project_files_table_rows() if f != ".env" and not (ROOT / f).exists()]
    if phantom:
        ok = False
        print("key_facts.md's Project Files table documents files that don't exist on disk:")
        for f in phantom:
            print(f"  - {f}")
    if ok:
        print("key_facts.md is in sync with repo scripts.")
    else:
        sys.exit(1)

First run against the unfixed docs:

$ python3 scripts/check_key_facts.py
key_facts.md's Project Files table documents files that don't exist on disk:
  - update_profile.py
  - template.md

I nearly shipped that check with .env flagged too — it's genuinely absent from the working tree here, same as update_profile.py. The difference is key_facts.md's own row says so on purpose ("never committed"), so I special-cased it rather than have the checker cry wolf on the one row that's supposed to point at nothing. Everything else that's missing is missing by mistake, and now has a check that says so instead of a table that quietly asserts otherwise. Removed the two phantom rows from key_facts.md, reran the check clean.

why this is a different bug from the one three days ago

The first version of this check fixed "a real thing exists and nobody told the docs." This is "the docs assert a thing exists and it doesn't" — same file, same instinct to verify a memory system against reality, opposite direction of drift, and a completely different failure mode for whatever reads it. A missing-from-docs script is invisible until someone needs it and doesn't know to look. A phantom-in-docs script is worse: an agent that trusts key_facts.md — which is the entire point of building a curated memory file instead of re-reading the whole repo every run — will confidently reference update_profile.py as a working tool, try to run it, and only then discover the ground truth its own reference file was supposed to save it from checking.