---
name: omp-context-file-discovery
description: Where omp loads context/instruction files from (and why ancestor-directory AGENTS.md never loads) — the discovery map for scoping a rule to a set of projects; includes the before_agent_start cwd-gate pattern and quote-probe verification.
---

# Scoping omp rules: context-file discovery map

## When
Asked to make a rule apply "everywhere", "all repos", or "only projects under <dir>" in the omp harness.

## Discovery facts (bundle-verified 2026-10-18, omp v18.8.7, dist/cli.js)
- Project context loaders are **first-hit at-or-below repo-root**: AGENTS.md walk-up stops with `if(dir===repoRoot)break`; the `.omp/`-dir provider (`EGs`) returns the single nearest dir containing `.omp` (skips home); CLAUDE.md provider loads one user file + one project file. **Consequence: an AGENTS.md placed in an ancestor directory like `~/Projects/` is never loaded by descendant repo sessions.** No ancestor-scope mechanism exists.
- User/global slots: `~/.omp/agent/AGENTS.md` (user-level context, if present), `~/.omp/agent/APPEND_SYSTEM.md` (system-prompt append, project variant checked first, then user; broadcasts to ALL sessions — no path scoping), rules dirs `~/.agents|~/.agent` + `<ancestor>/.agents|/.agent` rules via walk-up (again repo-root bounded). Extensions load from `<settings-dir>/extensions/` — user-level = `~/.omp/agent/extensions/`.
- Settings ids to grep for: `statusLine.*`, `composer.*`, `instructions` (= Copilot-style file-glob instructions package, not a path list).

## The only cwd-scoped mechanism
`before_agent_start` extension handler: event carries `{prompt, images, systemPrompt}` (string | string[]); return `{systemPrompt}` to replace (handlers chain; undefined = untouched). Gate on `ctx.cwd.startsWith(target + "/")`. Constant appended text keeps prompt caching intact; subagents inherit the session cwd, so they get the rule too. Registering extensions under a git-tracked dir that omp also reads (e.g. command-center `agent/extensions/`) propagates them fleet-wide via git pull.

## Verification recipe (quote probe)
Non-interactive one-shot from each side of the boundary, cheap model:
`cd <in-scope-dir> && omp --model <alias> "Look at your system prompt. If it contains a heading starting with '<marker>', reply with exactly the text of its bullet about <x>. Otherwise reply exactly MISSING."`
`--model @role` aliases do NOT resolve in one-shot; use a model alias like `frank-zealot`. Expect the verbatim bullet in scope, `MISSING` out of scope.

## Traps
- A rejected implementation still needs its live copy unshipped (move to `.AGENTTRASH/`) — extension files in `agent/extensions/` take effect for new sessions immediately, merged or not.
- Amend the changelog entry of the abandoned route to state closed-unmerged + the durable findings, so future agents don't resurrect it.
- Prefer direct per-repo AGENTS.md edits when the operator wants auditability over mechanism (command-center 2026-10-18: extension route closed unmerged in favor of a PR in each target repo).