docs: add module-level AGENTS.md for mcp-oauth, atlas, rules-injector, background-task, call-omo-agent, lsp

🤖 Generated with assistance of [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)
2026-02-19 03:15:27 +09:00
parent 73514ed329
commit a28e989f83
6 changed files with 345 additions and 0 deletions
@@ -0,0 +1,64 @@
+# src/hooks/atlas/ — Master Boulder Orchestrator
+
+**Generated:** 2026-02-19
+
+## OVERVIEW
+
+17 files (~1976 LOC). The `atlasHook` — Continuation Tier hook that monitors session.idle events and forces continuation when boulder sessions (ralph-loop, task-spawned agents) have incomplete work. Also enforces write/edit policies for subagent sessions.
+
+## WHAT ATLAS DOES
+
+Atlas is the "keeper of sessions" — it tracks every session and decides:
+1. Should this session be forced to continue? (if boulder session with incomplete todos)
+2. Should write/edit be blocked? (policy enforcement for certain session types)
+3. Should a verification reminder be injected? (after tool execution)
+
+## DECISION GATE (session.idle)
+
+```
+session.idle event
+  → Is this a boulder/ralph/atlas session? (session-last-agent.ts)
+  → Is there an abort signal? (is-abort-error.ts)
+  → Failure count < max? (state.promptFailureCount)
+  → No running background tasks?
+  → Agent matches expected? (recent-model-resolver.ts)
+  → Plan complete? (todo status)
+  → Cooldown passed? (5s between injections)
+  → Inject continuation prompt (boulder-continuation-injector.ts)
+```
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `atlas-hook.ts` | `createAtlasHook()` — composes event + tool handlers, maintains session state |
+| `event-handler.ts` | `createAtlasEventHandler()` — decision gate for session.idle events |
+| `boulder-continuation-injector.ts` | Build + inject continuation prompt into session |
+| `system-reminder-templates.ts` | Templates for continuation reminder messages |
+| `tool-execute-before.ts` | Block write/edit based on session policy |
+| `tool-execute-after.ts` | Inject verification reminders post-tool |
+| `write-edit-tool-policy.ts` | Policy: which sessions can write/edit? |
+| `verification-reminders.ts` | Reminder content for verifying work |
+| `session-last-agent.ts` | Determine which agent owns the session |
+| `recent-model-resolver.ts` | Resolve model used in recent messages |
+| `subagent-session-id.ts` | Detect if session is a subagent session |
+| `sisyphus-path.ts` | Resolve `.sisyphus/` directory path |
+| `is-abort-error.ts` | Detect abort signals in session output |
+| `types.ts` | `SessionState`, `AtlasHookOptions`, `AtlasContext` |
+
+## STATE PER SESSION
+
+```typescript
+interface SessionState {
+  promptFailureCount: number  // Increments on failed continuations
+  // Resets on successful continuation
+}
+```
+
+Max consecutive failures before 5min pause: 5 (exponential backoff in todo-continuation-enforcer).
+
+## RELATIONSHIP TO OTHER HOOKS
+
+- **atlasHook** (Continuation Tier): Master orchestrator, handles boulder sessions
+- **todoContinuationEnforcer** (Continuation Tier): "Boulder" mechanism for main Sisyphus sessions
+- Both inject into session.idle but serve different session types
@@ -0,0 +1,53 @@
+# src/hooks/rules-injector/ — Conditional Rules Injection
+
+**Generated:** 2026-02-19
+
+## OVERVIEW
+
+19 files (~1604 LOC). The `rulesInjectorHook` — Tool Guard Tier hook that auto-injects AGENTS.md (and similar rule files) into context when a file in a directory is read, written, or edited. Proximity-based: closest rule file to the target path wins.
+
+## HOW IT WORKS
+
+```
+tool.execute.after (read/write/edit/multiedit)
+  → Extract file path from tool output
+  → Find rule files near that path (finder.ts)
+  → Already injected this session? (cache.ts)
+  → Inject rule content into tool output (injector.ts)
+```
+
+## TRACKED TOOLS
+
+`["read", "write", "edit", "multiedit"]` — triggers only on file manipulation tools.
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `hook.ts` | `createRulesInjectorHook()` — wires cache + injector, handles tool events |
+| `injector.ts` | `createRuleInjectionProcessor()` — orchestrates find → cache → inject |
+| `finder.ts` | `findRuleFiles()` + `calculateDistance()` — locate AGENTS.md near target path |
+| `rule-file-finder.ts` | Walk directory tree to find AGENTS.md / .rules files |
+| `rule-file-scanner.ts` | Scan for rule files in a directory |
+| `matcher.ts` | Match file paths against rule file scope |
+| `rule-distance.ts` | Calculate path distance between file and rule file |
+| `project-root-finder.ts` | Find project root (stops at .git, package.json) |
+| `output-path.ts` | Extract file paths from tool output text |
+| `cache.ts` | `createSessionCacheStore()` — per-session injection dedup |
+| `storage.ts` | Persist injected paths across tool calls |
+| `parser.ts` | Parse rule file content |
+| `constants.ts` | Rule file names: `AGENTS.md`, `.rules`, `CLAUDE.md` |
+| `types.ts` | `RuleFile`, `InjectionResult`, `RuleFileScope` |
+
+## RULE FILE DISCOVERY
+
+Priority (closest → farthest from target file):
+1. Same directory as target file
+2. Parent directories up to project root
+3. Project root itself
+
+Same-distance tie: all injected. Per-session dedup prevents re-injection.
+
+## TRUNCATION
+
+Uses `DynamicTruncator` — adapts injection size based on model context window (1M context models get full content, smaller models get truncated summaries).