Development record
The user's directory is theirs
The rule. A user is never surprised by a directory filling with things
they did not make. A tool creates files and directories only in space that was
handed to it — its own machine-scoped home under ~/.abcd.noindex/, or the tiers of a
checkout the record declares — and never beside the user's projects, in a
parent directory, or anywhere the user did not point it. What it puts in its
own space, it can list and reclaim.
Why. A directory is the user's map of their own work: what is there is what they made, and a folder that fills on its own stops being a map. The 2026-09-06 session that created twenty-two worktrees beside the other projects of the person who ran it did nothing wrong by isolating — parallel sessions need separate checkouts — and everything wrong by location; the objection was not "why so many" but "I don't want a user to be surprised that a folder is all of a sudden full of stuff". Twenty-one spent worktrees had already been cleared by hand five days earlier (iss-2609020721142452). An agent works unattended on trust, and a surprise in the user's own directory is what spends it. adr-2609091248200336 records the ruling; this file carries the stance.
Bounds.
- Isolation is not the violation. The checkout is the unit of isolation
(
AGENTS.md§ Concurrent sessions) and a parallel session needs its own; the rule governs where that checkout lands, not whether it exists. - The checkout is handed over on the record's terms.
.abcd/.work.local/is scratch by declaration and the repository root is not — a file guessed onto the root is astray_root_docsfinding — and beside the checkout there is no declared tier at all. - A directory the user made by hand is theirs even inside the tool's own store: it is listed, never moved, never removed. The store deletes only what it can prove it created, the stance embark's destination gate already takes (adr-35).
- Adjacent, not the same:
durable-state-lives-where-the-platform-says-it-surviveschooses a location by what outlives the platform's lifecycle; this rule chooses by whose space it is. A sibling directory survives every platform event and still belongs to the user.
Enforcement. None on the write side. The read side exists: the loader
refuses a configuration root the caller does not own, and only
~/.abcd.noindex/trusted-roots re-admits it. The store this rule points at — a
root-SHA-keyed ~/.abcd.noindex/worktrees/ lane, a verb that lists it, a verb that
reclaims a merged worktree, a line on the status board — is
itd-2609091014076309,
planned and unbuilt. Until it ships the rule is applied by hand: a session that needs a
worktree puts it under ~/.abcd.noindex/worktrees/<root-sha>/<name>/, the location
adr-2610031751065746
sets, a verifier's
copy goes outside every working tree, in a directory of its own under
~/.abcd.noindex/ keyed on the root-commit SHA (the session's scratchpad only
for a copy the same turn makes and discards), never
.abcd/.work.local/scratch/, and a reviewer
who sees a directory
appear beside a checkout names it.
Promotion. The intent's verbs promote the store half; a check that counts
a repository's worktrees outside the store, and a hazard-registry entry that
makes abcd guard refuse a git worktree add aimed at a parent directory,
would make the rule checkable and promote it to a discipline.
.abcd/development/principles/the-users-directory-is-theirs.md
open on GitHub ↗ · commit history ↗
mentions5
- adr-35The lifeboat is a coverage experiment — read-only, out-of-tree, and proven before it is packed (supersedes adr-4)
- adr-2609091248200336A tool never creates directories in user-owned project space; the store's location binds now and its verbs bind when the store ships
- adr-2610031751065746The worktree store lives under the renamed home, `~/.abcd.noindex/worktrees/<root-sha>/<name>/`, and the rest of its rule is unchanged
- iss-2609020721142452Worktrees for parallel lanes are created one directory above the repository (../abcd-wt-<lane>, ../abcd-f185, ../abcd-integration), which litters the parent directory with a dozen sibling checkouts named by convention only, leaves them behind when a session dies (21 spent worktrees, 1.4G, were removed by hand on 2026-09-01), and gives nothing a stable place to look for them. Assessment of where they should go: (1) inside the repository under .abcd/.work.local/worktrees/ keeps them with their owner and gitignored, but a worktree inside the main working tree is walked by every tree scan (the payload gate, name-guard, docs-lint), which already flakes during worktree creation (iss-2608261331317889) and would slow every gate; (2) under the user-level home, ~/.abcd/worktrees/<root-sha>/<branch-slug>/, keyed the way the history store already keys a repository by its root commit, keeps them out of every scan, survives a session, and gives an abcd verb a place to list, prune and reattach them; (3) the git default (anywhere) is the status quo. Option 2 fits the existing home layout and the one-canonical-primitive rule (the root-sha keying exists), and it makes the concurrent-sessions convention in AGENTS.md checkable: a session lists its peers' worktrees by reading one directory. It needs: a verb or documented one-liner (abcd worktree add <lane> / list / prune), the AGENTS.md convention updated, the lane brief updated, and a prune rule for worktrees whose branch is merged.
- itd-2609091014076309Session and agent worktrees live in a machine-scoped store that abcd lists and reclaims, never beside the user's own projects