← Blog
✎article de blog

The ledger blocked a harmless ls, because the answer was already known

A grey steel filing cabinet with one drawer half open behind a clear acrylic guard panel, in teal and steel with a warm amber desk lamp, the AMARBARO mark and wordmark centred over it.

A tripwire in our tooling ledger blocks a read-only ls into a relocated virtual environment, because three sessions repeated the same hand diagnosis that one command answers in full.

A plain ls into one of our Python environments now gets refused. The refusal is not a bug. The environment has been moved since it was built, its config files still point at the old path, and the guard knows the full answer before it blocks anything.

We built the guard because the same hand diagnosis was repeated three times, by three separate coding sessions. The guard's own comment puts the cost at about an hour of hand diagnosis, not data loss.

What a relocated environment does

A virtual environment, or venv, is a folder of Python packages that one project uses. A venv carries absolute paths in its config file and in its cached bytecode. Move the folder and those paths still name the old location.

The result is confusing rather than broken. Tracebacks and pytest warnings cite files from a different repository, or from one that no longer exists. The program may still run fine. A reader who inspects the start-up scripts by hand sees paths that look like a second project and draws the wrong conclusion.

The guard reads the answer before it blocks

The guard runs the diagnosis tool first. The tool is venv-doctor. When the environment is healthy, the tool exits 0 and the guard stays silent, however much anyone pokes at the folder. It fires only when the tool exits 1, meaning the environment is relocated.

So the block is conditional on knowledge. It does not stop a question the tooling cannot answer. It stops a hand reading whose answer is already in hand.

The deny message is the fix

A blocked call still gets the answer. The message names the one full diagnosis, venv-doctor on that folder, and the one cleanup, venv-doctor with the pycache flag, which silences the stale paths. It also states the repetition count, so the next session knows this is a known trap and not a fluke.

We think that is the right shape for a guard. A refusal that only says no sends the session back to the same hand reading. A refusal that carries the fix ends the search.

What the guard actually matches

A shebang is the first line of a script. It names the interpreter the script runs under. In a relocated environment that line still names the old path, which looks like a fault and is only a stale address. That is why the deny message says not to read the start-up scripts by hand.

The guard matches the read commands ls, cat, head, stat, readlink and file when they point into the environment's bin folder or its config file. It does not match a read of the rest of the project. The block is narrow: one folder, a handful of commands, and only when the tool has confirmed the move.

Why a guard and not only a note

The lesson about relocated environments was already written in the ledger before the guard. Our rule for repeated mistakes is that the lesson becomes a gate, in the same turn, so that the next session meets the rule at the moment it would repeat the mistake, not only when it happens to read the file. The guard is that step.

The trade is clear. A guard that fires on a harmless call costs one blocked command. A repeated hand diagnosis costs a stretch of reading and a wrong turn, and the guard message ends that stretch in one line.

What the ledger costs

The guard lives in a tooling ledger, the file where each mistake becomes a dated entry with a rule attached. That file runs to 2,607 lines. The venv guard is one short entry among hundreds of others, and a session that does not read the ledger first will not see the rule until the guard fires.

What we still do not know

  • How often the guard has fired, and how often a session got past it with a hand read anyway. We have not counted.
  • Whether the repetitions came before or after the guard was written. The deny message counts three repeats but does not give their dates against the guard.
  • Whether other repeated diagnoses should carry the same kind of verify step. We have one. We have not looked for the rest.

Provenance

  • ~/Brain/SINDEX/tooling.md: the venv-hand-diagnosis guard entry, its verify step that runs venv-doctor and blocks only on exit code 1, and its deny message stating the three repeats. The file is 2,607 lines long.

Commentaires

Pas encore de commentaires.

Se connecter pour commenter.