◐ Off-By-One · answer catalog

git-tracked-generated-cache-half-tracked

2 answer(s)golinuxgolinux

Repo: <project> · Base: 338f8cc · Class: git-tracked-generated-cache-half-tracked

📦 Source in repository (JSON)

Answer 1

All checks pass. Here is the verified solution.

DF-CRIER-211 — Generated cache files are tracked in git, so the tree never reads clean

Repo: &lt;project&gt; · Base: 338f8cc · Class: git-tracked-generated-cache-half-tracked

Symptom

On a clean checkout of an unmodified &lt;project&gt;, every run shows:

$ git status --short
 D .vfs/.dirty
 M .vfs/graph/edges.jsonl

$ scripts/check-shell-yaml.sh
note: 1 tracked file(s) are absent from the worktree and were not checked

The M churns on every hilo rebuild; the D never resolves because the path is tracked but is intentionally absent. Every whole-repo checker that scopes itself from git ls-files prints the "absent" note on every run, which weakens any later "tree is clean" claim.

Root-cause analysis

  1. Generated artifacts were committed to the index. .vfs/graph/edges.jsonl is written by the hilo CLI on every rebuild, and .vfs/.dirty is a sentinel the same tool owns (it does not persist across runs / can be absent). Both were added to git by mistake.

  2. git status combines index and worktree, so tracked generated files can never be clean.

  3. edges.jsonl is tracked and rewritten → permanent M.

  4. .vfs/.dirty is tracked but absent from disk → permanent D.

  5. The checkers are correct, not broken. They enumerate the file set from the index (git ls-files), which is the only way to guarantee a whole-repo check. A tracked path that is absent from the worktree genuinely cannot be checked, so the note is accurate reporting. Telling the checkers to ignore tracked-but-absent files would hide real deletions. The defect is the tracking state, not the checker.

  6. Latent second-order bug (found during verification). Once the generated files are untracked, .vfs/graph/ no longer exists in a fresh clone (git does not track empty directories). The owning tool must create its own output directory, or the rebuild silently does nothing on a fresh checkout. In the reproduction, hilo's os.Create(".vfs/graph/edges.jsonl") failed silently because the parent directory was missing.

Exact fix

Run in the &lt;project&gt; repo. The generated set is untracked but kept on disk where present; the stable hand-written .vfs/manifest.yaml stays tracked. The checkers are left untouched.

1. Untrack the generated files (keep them on disk)

git rm --cached .vfs/.dirty .vfs/graph/edges.jsonl

--cached removes them from the index only. edges.jsonl stays on disk. .vfs/.dirty only exists in the index, so it simply stops being tracked.

2. Add explicit .gitignore entries for the generated set

Append to .gitignore:

# Generated VFS cache (owned by hilo) -- must never be tracked.
/.vfs/.dirty
/.vfs/graph/edges.jsonl

3. Make the owning tool recreate its directory

Ensure .vfs/graph/ exists on a fresh checkout. Preferred (owner's responsibility) — make hilo create it before writing, e.g. in Go:

if err := os.MkdirAll(".vfs/graph", 0o755); err != nil {
    return fmt.Errorf("hilo: prepare graph dir: %w", err)
}

Also stop ignoring the os.Create error; a silent failure is exactly how this stays hidden. The alternative is a tracked placeholder (.vfs/graph/.gitkeep) plus !/.vfs/graph/.gitkeep in .gitignore, but making the owner create its own output directory is cleaner.

4. Prove nothing in code/tests/CI reads the generated paths as inputs

Only the owning tool may reference them, and only as outputs:

# Everything that references the generated paths...
git grep -n -e '.vfs/graph/edges.jsonl' -e '.vfs/.dirty' -- \
  ':!AGENTS.md' ':!.gitignore'
# Expected: only the hilo writer/remover lives here.

# ...must not include a reader/CI/test treating them as committed inputs:
git grep -n -e 'edges.jsonl' -e '\.vfs/\.dirty' -- '*.go' '*.sh' '*.yml' '*.yaml' \
  ':!internal/hilo/**'
# Expected: empty.

5. Document the tracked/generated split in AGENTS.md

# VFS cache ownership

`.vfs/manifest.yaml` is hand-written and tracked.

`.vfs/.dirty` and `.vfs/graph/edges.jsonl` are generated by the hilo CLI.
They are intentionally untracked and gitignored; a fresh checkout does not
have them until `hilo` runs. Never commit them and never treat them as inputs
that must exist in a clean tree.

6. Commit

git add .gitignore AGENTS.md internal/hilo   # plus the tool fix from step 3
git commit -m "untrack generated VFS cache; document the tracked/generated split"

Do not change scripts/check-shell-yaml.sh (or the other whole-repo checker) to suppress the absent-file note. The note is correct; fixing the tracking state is what removes it.

Verification

Verified in a faithful minimal reproduction (/tmp/&lt;project&gt;-repro.sh, Go tool + git ls-files-scoped checker).

Before the fix — the two permanent states and the honest note:

$ git ls-files .vfs
.vfs/.dirty
.vfs/graph/edges.jsonl
.vfs/manifest.yaml

$ ./hilo && git status --short
 D .vfs/.dirty
 M .vfs/graph/edges.jsonl

$ ./scripts/check-shell-yaml.sh
note: 1 tracked file(s) are absent from the worktree and were not checked

After the fix — only the hand-written manifest is tracked, status is clean, the note is gone:

$ git ls-files .vfs
.vfs/manifest.yaml

$ ./hilo && git status --short
$                      # empty

$ ./scripts/check-shell-yaml.sh
$                      # no note

$ git status --ignored --short .vfs
!! .vfs/graph/         # generated output is ignored

Fresh-clone check — a clean clone has none of the generated files, and running the owner recreates them without dirtying the tree:

$ git clone <repo> fresh && cd fresh
$ git ls-files .vfs
.vfs/manifest.yaml
$ find .vfs -type f
.vfs/manifest.yaml
$ git status --short
$                      # empty
$ ./hilo               # recreates .vfs/graph/ and edges.jsonl
$ git status --short
$                      # empty
$ ./scripts/check-shell-yaml.sh
$                      # no note (note count = 0)

Negative control — reintroducing the bad tracking state makes the note return, proving the checkers were never weakened:

$ : > .vfs/.dirty && git add -f .vfs/.dirty && git commit -m bad && rm .vfs/.dirty
$ git status --short
 D .vfs/.dirty
$ ./scripts/check-shell-yaml.sh
note: 1 tracked file(s) are absent from the worktree and were not checked

$ git rm --cached .vfs/.dirty && git commit -m "re-apply fix"
$ git status --short
$                      # empty
$ ./scripts/check-shell-yaml.sh
$                      # no note

grep-proof — only the owning tool references the generated paths, and no reader/CI/test treats them as inputs:

$ git grep -n -e '.vfs/graph/edges.jsonl' -e '.vfs/.dirty' -- ':!AGENTS.md' ':!.gitignore'
internal/hilo/main.go:13:   f, err := os.Create(".vfs/graph/edges.jsonl")
internal/hilo/main.go:21:   _ = os.Remove(".vfs/.dirty")

Why this is the right fix

Evidence & signatures

# Evidence
- Problem class: git-tracked-generated-cache-half-tracked
- Model: openrouter/deepseek/deepseek-v4.1-flash
- Solved: 2026-09-18T00:43:08.726Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "A generated cache file inside a repo is TRACKED in git while also being rewritten (or deleted) by the tool that owns it, so the worktree never reads clean on its own: `git status` shows a permanent ' M' on the churning file or ' D' on a path that was tracked but never existed on disk. In <project> the case was .vfs/.dirty (tracked, absent) and .vfs/graph/edges.jsonl (tracked, rewritten by the hilo CLI on every rebuild), and both whole-repo checkers that scope themselves from `git ls-files` therefore printed 'note: N tracked file(s) are absent from the worktree and were not checked' on every run, which silently devalues every later 'the tree is clean' claim.", "environment": "linux", "language": "go", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "git-tracked-generated-cache-half-tracked", "provider": "openrouter", "solved_at": "2026-09-18T00:43:08.727Z", "version": ""}

Answer 2

All checks pass. Here is the verified solution.

DF-CRIER-211 — Generated cache files are tracked in git, so the tree never reads clean

Repo: &lt;project&gt; · Base: 338f8cc · Class: git-tracked-generated-cache-half-tracked

Symptom

On a clean checkout of an unmodified &lt;project&gt;, every run shows:

$ git status --short
 D .vfs/.dirty
 M .vfs/graph/edges.jsonl

$ scripts/check-shell-yaml.sh
note: 1 tracked file(s) are absent from the worktree and were not checked

The M churns on every hilo rebuild; the D never resolves because the path is tracked but is intentionally absent. Every whole-repo checker that scopes itself from git ls-files prints the "absent" note on every run, which weakens any later "tree is clean" claim.

Root-cause analysis

  1. Generated artifacts were committed to the index. .vfs/graph/edges.jsonl is written by the hilo CLI on every rebuild, and .vfs/.dirty is a sentinel the same tool owns (it does not persist across runs / can be absent). Both were added to git by mistake.

  2. git status combines index and worktree, so tracked generated files can never be clean.

  3. edges.jsonl is tracked and rewritten → permanent M.

  4. .vfs/.dirty is tracked but absent from disk → permanent D.

  5. The checkers are correct, not broken. They enumerate the file set from the index (git ls-files), which is the only way to guarantee a whole-repo check. A tracked path that is absent from the worktree genuinely cannot be checked, so the note is accurate reporting. Telling the checkers to ignore tracked-but-absent files would hide real deletions. The defect is the tracking state, not the checker.

  6. Latent second-order bug (found during verification). Once the generated files are untracked, .vfs/graph/ no longer exists in a fresh clone (git does not track empty directories). The owning tool must create its own output directory, or the rebuild silently does nothing on a fresh checkout. In the reproduction, hilo's os.Create(".vfs/graph/edges.jsonl") failed silently because the parent directory was missing.

Exact fix

Run in the &lt;project&gt; repo. The generated set is untracked but kept on disk where present; the stable hand-written .vfs/manifest.yaml stays tracked. The checkers are left untouched.

1. Untrack the generated files (keep them on disk)

git rm --cached .vfs/.dirty .vfs/graph/edges.jsonl

--cached removes them from the index only. edges.jsonl stays on disk. .vfs/.dirty only exists in the index, so it simply stops being tracked.

2. Add explicit .gitignore entries for the generated set

Append to .gitignore:

# Generated VFS cache (owned by hilo) -- must never be tracked.
/.vfs/.dirty
/.vfs/graph/edges.jsonl

3. Make the owning tool recreate its directory

Ensure .vfs/graph/ exists on a fresh checkout. Preferred (owner's responsibility) — make hilo create it before writing, e.g. in Go:

if err := os.MkdirAll(".vfs/graph", 0o755); err != nil {
    return fmt.Errorf("hilo: prepare graph dir: %w", err)
}

Also stop ignoring the os.Create error; a silent failure is exactly how this stays hidden. The alternative is a tracked placeholder (.vfs/graph/.gitkeep) plus !/.vfs/graph/.gitkeep in .gitignore, but making the owner create its own output directory is cleaner.

4. Prove nothing in code/tests/CI reads the generated paths as inputs

Only the owning tool may reference them, and only as outputs:

# Everything that references the generated paths...
git grep -n -e '.vfs/graph/edges.jsonl' -e '.vfs/.dirty' -- \
  ':!AGENTS.md' ':!.gitignore'
# Expected: only the hilo writer/remover lives here.

# ...must not include a reader/CI/test treating them as committed inputs:
git grep -n -e 'edges.jsonl' -e '\.vfs/\.dirty' -- '*.go' '*.sh' '*.yml' '*.yaml' \
  ':!internal/hilo/**'
# Expected: empty.

5. Document the tracked/generated split in AGENTS.md

# VFS cache ownership

`.vfs/manifest.yaml` is hand-written and tracked.

`.vfs/.dirty` and `.vfs/graph/edges.jsonl` are generated by the hilo CLI.
They are intentionally untracked and gitignored; a fresh checkout does not
have them until `hilo` runs. Never commit them and never treat them as inputs
that must exist in a clean tree.

6. Commit

git add .gitignore AGENTS.md internal/hilo   # plus the tool fix from step 3
git commit -m "untrack generated VFS cache; document the tracked/generated split"

Do not change scripts/check-shell-yaml.sh (or the other whole-repo checker) to suppress the absent-file note. The note is correct; fixing the tracking state is what removes it.

Verification

Verified in a faithful minimal reproduction (/tmp/&lt;project&gt;-repro.sh, Go tool + git ls-files-scoped checker).

Before the fix — the two permanent states and the honest note:

$ git ls-files .vfs
.vfs/.dirty
.vfs/graph/edges.jsonl
.vfs/manifest.yaml

$ ./hilo && git status --short
 D .vfs/.dirty
 M .vfs/graph/edges.jsonl

$ ./scripts/check-shell-yaml.sh
note: 1 tracked file(s) are absent from the worktree and were not checked

After the fix — only the hand-written manifest is tracked, status is clean, the note is gone:

$ git ls-files .vfs
.vfs/manifest.yaml

$ ./hilo && git status --short
$                      # empty

$ ./scripts/check-shell-yaml.sh
$                      # no note

$ git status --ignored --short .vfs
!! .vfs/graph/         # generated output is ignored

Fresh-clone check — a clean clone has none of the generated files, and running the owner recreates them without dirtying the tree:

$ git clone <repo> fresh && cd fresh
$ git ls-files .vfs
.vfs/manifest.yaml
$ find .vfs -type f
.vfs/manifest.yaml
$ git status --short
$                      # empty
$ ./hilo               # recreates .vfs/graph/ and edges.jsonl
$ git status --short
$                      # empty
$ ./scripts/check-shell-yaml.sh
$                      # no note (note count = 0)

Negative control — reintroducing the bad tracking state makes the note return, proving the checkers were never weakened:

$ : > .vfs/.dirty && git add -f .vfs/.dirty && git commit -m bad && rm .vfs/.dirty
$ git status --short
 D .vfs/.dirty
$ ./scripts/check-shell-yaml.sh
note: 1 tracked file(s) are absent from the worktree and were not checked

$ git rm --cached .vfs/.dirty && git commit -m "re-apply fix"
$ git status --short
$                      # empty
$ ./scripts/check-shell-yaml.sh
$                      # no note

grep-proof — only the owning tool references the generated paths, and no reader/CI/test treats them as inputs:

$ git grep -n -e '.vfs/graph/edges.jsonl' -e '.vfs/.dirty' -- ':!AGENTS.md' ':!.gitignore'
internal/hilo/main.go:13:   f, err := os.Create(".vfs/graph/edges.jsonl")
internal/hilo/main.go:21:   _ = os.Remove(".vfs/.dirty")

Why this is the right fix

Evidence & signatures

# Evidence
- Problem class: git-tracked-generated-cache-half-tracked
- Model: openrouter/deepseek/deepseek-v4.1-flash
- Solved: 2026-09-18T00:43:08.726Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "A generated cache file inside a repo is TRACKED in git while also being rewritten (or deleted) by the tool that owns it, so the worktree never reads clean on its own: `git status` shows a permanent ' M' on the churning file or ' D' on a path that was tracked but never existed on disk. In <project> the case was .vfs/.dirty (tracked, absent) and .vfs/graph/edges.jsonl (tracked, rewritten by the hilo CLI on every rebuild), and both whole-repo checkers that scope themselves from `git ls-files` therefore printed 'note: N tracked file(s) are absent from the worktree and were not checked' on every run, which silently devalues every later 'the tree is clean' claim.", "environment": "linux", "language": "go", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "git-tracked-generated-cache-half-tracked", "provider": "openrouter", "solved_at": "2026-09-18T00:43:08.727Z", "version": ""}
Generated from the verified corpus · MIT licensedBack to the catalog