maintain-filemap · Loop

When the directory shape changes, regenerate the map. The committed FILEMAP.md at each repo root is the artifact a new collaborator opens first.

What this loop does

Keeps a FILEMAP.md at the root of each Lossless repo current with the actual on-disk tree. Each FILEMAP.md has two parts:

1. A curator preface — hand-authored prose explaining what each top-level directory IS (purpose, ownership, conventions). Edited rarely (only when the meaning of a directory changes, not when its contents do).
2. A generated tree — produced by tree -L 3 with a curated ignore set, spliced between <!-- TREE-START --> and <!-- TREE-END --> sentinels in a fenced code block. Regenerated by the loop's script every time the discipline fires.

Why both: a raw tree dump is useful but doesn't tell a newcomer what they're looking at. The curator preface is what makes the file legible; the generated tree is what makes it accurate.

When this loop fires

Three triggers:

The hook is optional but recommended. Without it, the discipline lives in the agent's working memory: "Did I just add corpus/? → regen FILEMAP."

What changes is a "directory-shape change"

Triggers the loop:

• A new top-level directory was added (mkdir context-v/loops/)
• A submodule was mounted or unmounted (.gitmodules changed)
• A major subsystem was renamed (apps/dididecks-shell/ → apps/deck-shell/)
• A top-level file like CLAUDE.md or pnpm-workspace.yaml was added
• A new client-site landed under client-sites/

Does NOT trigger the loop:

• A new file under an existing directory (e.g., adding context-v/plans/Some-Plan.md)
• A small refactor that doesn't change directory names
• A typo fix, dependency bump, or doc edit
• Adding a new variant under an existing client-site's src/pages/scroll/{deck}/

Rule of thumb: if the change makes the FILEMAP's depth-3 view different, run the loop.

The recipe

# From the repo root
bash context-v/loops/maintain-filemap/scripts/regen-filemap.sh

The script:

1. cd to the repo root (via git rev-parse --show-toplevel)
2. Runs tree -L 3 -I '<curated-ignore-pattern>' --noreport --dirsfirst
3. Reads the current FILEMAP.md
4. Splices the new tree between <!-- TREE-START --> and <!-- TREE-END --> markers, preserving everything else
5. Writes back to FILEMAP.md
6. Reports git diff status; if changed, suggests git add FILEMAP.md for the next commit

The ignore pattern is the load-bearing knob — see scripts/regen-filemap.sh for the canonical set (node_modules, .git, .astro, dist, .vercel, .output, cache, *.lock, .DS_Store, public). Edit only when a new "noise" directory consistently appears across repos.

The artifact

A FILEMAP.md at every repo root that participates. Per the pseudomonorepos discipline, every level of the tree has its own:

The PARENT's FILEMAP.md does NOT try to deeply enumerate submodule contents. It stops at the submodule mount + the submodule's own top-level dirs (depth 3 from parent ≈ depth 1 within submodule). For deeper detail, the reader follows the submodule's own FILEMAP.md.

Detection — how to tell the loop is overdue

Two signals:

1. Run the script. If git diff FILEMAP.md is non-empty after running, the committed map is stale. Trivial to catch.
2. Eyeball test. If you ls the repo root and see a directory that's not in FILEMAP.md, the loop is overdue.

A future enhancement: a CI check that runs the script and fails the build if git diff --quiet FILEMAP.md would fail. Today it's local-discipline; promote to CI when a collaborator misses the discipline twice.

Composition with other skills

Anti-patterns

• Don't auto-commit FILEMAP.md from a hook. The regen should stage the file but let the human approve. Auto-commits churn git history with no-op commits when the tree didn't actually change.
• Don't autogenerate the curator preface. The preface is what makes the file legible; an LLM-generated "this directory contains files" preface is worse than no preface at all.
• Don't try to render submodule contents deeply in the parent. Submodules carry their own FILEMAP. Parent stops at depth 3 and links into children.
• Don't ignore the ignore set. Generated dist/ directories, node_modules/, and .lock files in the tree are noise that makes the map unreadable. The curated ignore pattern is load-bearing.

See also

• scripts/regen-filemap.sh — the recipe
• Each repo's FILEMAP.md — the artifact this loop maintains
• Parent loops README: ../README.md
• Companion skills under context-v/agent-skills/