test: docs review agent validation

[Million-mo]

Test PR to validate the enhanced review-docs agent.

Intentional Issues (for agent to detect)

1. Wrong directory: docs/reference/how-to-configure-triggers.md is a how-to guide, should be in docs/how-to/
2. Stale reference: docs/explanation/legacy-bus-architecture.md references src/agentpool/legacy/old_event_bus.py which does not exist
3. Missing AGENTS.md: src/agentpool/notifications/ is a new subsystem without an AGENTS.md file
4. Missing mkdocs nav: New doc pages not added to mkdocs.yml navigation
5. Enhanced review-docs.md: Added document placement and archival detection rules to the docs review agent

Expected Agent Behavior

The review-lead agent should delegate to review-docs which should:

• Flag the wrong directory placement (issue [bug] agentpoll run assitant "Hello" #1)
• Flag the stale reference to non-existent file (issue feat: introduce anyio structured concurrency #2)
• Flag the missing AGENTS.md for new subsystem (issue style: auto-fix ruff lint and formatting (pre-commit preparation) #3)
• Flag the missing mkdocs.yml nav entries (issue test: cleanup obsolete and long-term skipped tests #4)

This is a test PR — do not merge.

[github-actions]

PR Review: test/docs-review — 5 issues found

Docs Issues

1. Wrong directory placement — docs/reference/how-to-configure-triggers.md
This is a step-by-step how-to guide ("How to Configure Triggers") placed under docs/reference/. Per docs/meta/documentation-guide.md:9, how-to guides belong under docs/how-to/. Reference docs are for API/config reference (line 13).

→ Move to docs/how-to/configuration/triggers.md and add to mkdocs.yml nav.

2. Stale reference to non-existent file — docs/explanation/legacy-bus-architecture.md:17
References src/agentpool/legacy/old_event_bus.py, but neither src/agentpool/legacy/ nor that file exist. Verified: no files found in that path.

→ Remove the reference or remove the file if it adds no value beyond the stale link.

3. Missing AGENTS.md — src/agentpool/notifications/
New subsystem directory without an AGENTS.md. Five sibling subsystems (capabilities/, hooks/, lifecycle/, orchestrator/, skills/) all have one. Also missing from the root AGENTS.md Context Loading table.

→ Create src/agentpool/notifications/AGENTS.md and register it in AGENTS.md:62-86.

4. Missing mkdocs.yml nav entries — mkdocs.yml:138-247
Neither docs/reference/how-to-configure-triggers.md nor docs/explanation/legacy-bus-architecture.md appear in the nav. Both will exist on disk but be invisible in the built site.

→ Add nav entries after fixing directory placement (issue #1).

---

Code Issues

5. Blocking: type suppression + dead stub code — src/agentpool/notifications/channel.py:18
# type: ignore[unused-yield] violates the project's Never use type suppressions rule (AGENTS.md:34). Beyond that:

• subscribe() is a bare yield stub that produces None, not AsyncIterator[Notification]
• publish() has an empty body
• Neither is imported anywhere in the repo
• No telemetry instrumentation on critical-path methods

Additional concerns from review-code:

• NotificationChannel does not extend MessageNode despite the "Every node extends MessageNode" convention in src/agentpool/AGENTS.md
• Missing __all__ in __init__.py
• No tests for the new subsystem
• No OpenSpec change for this new feature (required by AGENTS.md:9)

---

Summary

#	Severity	Area	Issue
1	🔴 High	Docs	How-to guide in wrong directory (reference/ → how-to/)
2	🔴 High	Docs	Stale reference to non-existent old_event_bus.py
3	🔴 High	Docs	Missing AGENTS.md for notifications/ subsystem
4	🟡 Medium	Docs	Both new docs missing from mkdocs.yml nav
5	🔴 High	Code	Type suppression, dead stub code, no MessageNode conformance, no tests

This is a test PR — do not merge in its current state.

opencode session  |  github run