**Class:** missing · **Severity:** material
**Flow:** arch-90c90751344f (adoption)
**Frequency:** unknown; one `docir init` in the wrong directory

## Finding

`docir init sub/` inside a repository that already has a `.docir/` at its root creates a
second store and says nothing about the first. Store discovery walks *up* for the nearest
`.docir`, so from that moment every command run anywhere under `sub/` resolves to the
nested store.

## What happens today

OBSERVED. Parent store initialised at the root with three documents; `docir init team/`
exits 0, stderr silent. `docir add` run from `team/` reports
`store: .../team/.docir` — also silent — and the document lands there. The parent store
holds 3 documents, the nested one holds 1, and `docir check` at the root cannot see the
nested document at all: it is not orphaned, not dangling, not anything. It is in a
different corpus.

## Impact

The failure is quiet in both directions. Nobody is told a second store was created, and
nobody is told which store a write landed in unless they read the `store` field. Documents
split across two corpora retrieve separately, so `docir context` from the root silently
stops returning half the project's decisions, and the CI gate over the root store passes
while the nested one is unchecked.

docir already recognises this class of problem and handles it elsewhere: a write that falls
back to the global `~/.docir` from inside a git repository warns on stderr, because "your
document landed in a store you may not have meant" is worth interrupting for
(`Settings.is_unintended_global_fallback`). A nested project store is the same sentence
with a different store.

Not a contradiction of adr-20eec6e2e2ca. That decision says `new_store_home` deliberately does not
walk up for an existing `.docir`, because reusing a parent store is the wrong answer when
the caller asked for a new one — and that is right. "Do not reuse it" and "do not mention
it" are different decisions, and only the first was made.

## Proposed default

`init` warns on stderr when `discover_project_home()` finds a store above the directory it
is about to create one in: name the enclosing store, say that commands run beneath the new
one will use the new one, and proceed. A flag (`--nested`) could silence it if the
shadowing is deliberate. Do not refuse: monorepo subprojects with their own stores are a
legitimate layout, which is why this is a warning rather than an error.

## Actors affected

- AI coding agent
- repository maintainer
- CI job

## Evidence

- `src/docir/config/settings.py` (`discover_project_home`, `new_store_home`,
  `is_unintended_global_fallback`)
- `src/docir/entry_points/composition.py` (`initialize_store`)
- PROBE-R7 / PROBE-R7b in the 2026-07-30 probe log

## Resolution

FIXED 2026-07-30. `docir init` now warns on stderr when a project store already exists above the one it is creating, naming the enclosing store and saying that commands run beneath the new one will use the new one and that the outer store's `check` will not see documents added there. `InitResult.enclosing_home` carries it, so the JSON path reports it too. It warns rather than refuses: a monorepo subproject with its own store is a legitimate layout, which is exactly why adr-20eec6e2e2ca has `init` create rather than reuse — the fix is to the silence, not to the rule. The check lives in `config/settings.enclosing_project_home`, beside `resolve` and `new_store_home`, for the reason recorded on the latter: a rule about which store is in play that lives anywhere else escapes the review that reads those two. It starts the walk at the store's own directory so an explicitly-named store (`--home /srv/docs`) still notices a sibling `.docir`, and skips a candidate equal to the new home so re-running `init` does not report the store against itself. Verified by injecting the bug: with the lookup stubbed to None, five of the eight new guards fail.