Ghost in the README: a séance for the promises our projects forget

xyx200 — Sun, 01 Nov 2026 02:19:21 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine.

What I Built

The most unsettling line in a README is sometimes the one that is no longer there.

“Everything works offline.”

“Every control is accessible with a keyboard.”

“Your recordings never leave your computer.”

A release arrives. The documentation gets shorter. Nothing in the diff tells us whether those promises were fulfilled, deliberately retired, or simply forgotten.

Ghost in the README is a small, local tool for that uncomfortable space. Give it two versions of a project document. An open-weight sentence model searches for the present-day echo of each old passage. It shows the words on both sides, their source lines, and how close the model thinks they are. Then it asks a person to decide: keep this promise, retire it deliberately, or investigate.

That is my interpretation of this week's theme: a project's abandoned intentions haunting its present. The ghost is not a simulated person. It is an unresolved piece of responsibility.

Demo

Watch the recorded CLI demo. This public page replays an actual recorded run; live inference runs locally using the setup instructions below.

The walkthrough uses genuine screenshots from successful browser inference, edited into a short sequence. The repository also includes demo/recording.html, a self-contained replay of the CLI's actual, unedited output. Both are explicitly labeled as recordings.

The main example is Lantern, a fictional oral-history archive created for this demo. In its old README, recordings stay on the user's device, transcripts can be exported, and every control works with a keyboard. In the new README, there are cloud processing and shareable links. Some promises survive in different words. Others have no close echo.

The export promise is a useful example. The model links “export every transcript as a plain text file” with “download your transcripts in TXT format.” In the recorded browser run, cosine similarity is about 0.711, while the word-overlap baseline is only 0.056. Literal overlap alone would miss much of that relationship.

Keyboard access is different. Its best match scores about 0.101. That does not prove the feature was removed. It tells the reviewer where the document has stopped accounting for it.

I marked that passage Investigate, left a note about restoring keyboard navigation or documenting its retirement, and exported the ledger. The downloaded JSON preserves the decision with the original text, source lines, scores, and input fingerprints.

Code

Public MIT-licensed source repository.

The project was started on October 29, 2026 UTC, within this challenge's window. The README includes setup, the CLI, model provenance, tests, screenshots, and limitations. No paid services or partner credits are required.

How I Built It

The runtime AI is Sentence Transformers all-MiniLM-L6-v2, using Xenova's ONNX conversion. Both model repositories identify the license as Apache 2.0. Transformers.js 3.8.1 and ONNX Runtime execute the quantized model locally.

The flow is deliberately inspectable:

Parse English prose into passages while keeping original line numbers. Skip headings and fenced code.
Encode each passage into a normalized, 384-dimensional vector using mean pooling.
Retrieve the nearest current passage for every old passage using cosine similarity.
Show alternatives, the gap to the runner-up, shared matches, and a Jaccard word-overlap baseline.
Keep the reviewer's decision separate from the model's score.

In the browser, inference runs in a Web Worker so the page can remain interactive. A shared core module powers the CLI and interface. The model files and WASM runtime are downloaded during setup and then served locally. Remote model loading is disabled; the page also restricts network connections to its own origin.

There is no generative step. The app cannot invent a promise, silently rewrite a source, or attribute a new sentence to an old maintainer. Its eerie language is interface copy; the semantic matching is actual model inference.

The model download is 22.81 MiB. One observed browser run encoded 13 passages in 133 ms, excluding model loading. That is a measurement from this host, not a promise about every laptop. The evidence bundle includes CPU output, browser output, model revision and hashes, and the exact fictional inputs.

Ten core tests passed after independent review. Five small, synthetic retrieval checks also passed: each intended paraphrase outranked an unrelated sentence by at least 0.15 cosine. These are sanity checks, not a representative benchmark. The prepared CPU inference path was also run with network fetching disabled. Browser checks covered real WASM inference, both report downloads, preserved review notes, empty-input validation, and a narrow mobile layout.

The model's most useful mistake

The example that matters most is the one I would not let the model decide.

“All features work without an internet connection.”

“An internet connection is required to use all features.”

Their similarity is approximately 0.764. They occupy much of the same semantic territory and make opposite commitments.

This is why the app says possible echo, never promise fulfilled. A small vocabulary rule flags the change in negation, but that rule has limits too. It can over-warn, and it can miss contradictions expressed without an obvious “not.” Every result stays a review prompt.

The threshold slider does not turn similarity into certainty. It lets the reviewer inspect how an editorial cutoff changes the queue. The exported evidence keeps that threshold visible.

Why Does Open Innovation Matter?

A document like this can contain the history of a project before anyone is ready to explain it publicly. Sending every old plan to a remote model would make the tool less useful for exactly the conversations it is supposed to support.

Open weights make a small local review possible. After the initial downloads, neither an API account nor a metered inference service is needed. The browser keeps the text in memory; the CLI reads the supplied local files. Nothing needs to be uploaded to obtain a match.

Openness also makes the result challengeable. The model revision is pinned. The scoring code is short. The lexical baseline sits beside the embedding result. Someone can replace the encoder, change the thresholds, or test a failure without asking a service provider to expose its internals.

A closed service could provide good embeddings. The practical advantage here is that this particular archive can remain usable without depending on that service continuing to exist.

The Spirit of It

This project does not demand that every old promise live forever. Sometimes the kindest, most honest thing a maintainer can do is let one go.

The difference is leaving a reason.

A missing line says nothing. A small review note can say: we remember what we intended, we have looked at what changed, and this is what happens next.

That is the ending I wanted for these ghosts.

AI Assistance and Credits

Codex assisted with the concept, implementation, tests, verification, and writing. The application's runtime AI is the locally executed MiniLM model credited above. The samples are original fictional fixtures; no user study, real project incident, or testimonial is claimed. Original app material is MIT licensed, and pretrained weights and dependencies retain their own licenses. Full credits are in THIRD_PARTY.md.

This entry targets the overall challenge. No partner prize category is claimed.

DEV Community: xyx200