git:20260416.e329636 to git:20260416.8ee7080

+ This file contains shared infrastructure knowledge for all watcher instances.

+ Each watcher has its own identity in its subdirectory and its own LEARNINGS.md.

+ Agent sessions inspecting this directory will find the layout and CLI reference below.

+

+ ## Layout

+

+ The singular watcher root mirrors `~/.agent-deck/conductor/`:

+

+ ```

+ ~/.agent-deck/watcher/

+ CLAUDE.md — this file (shared knowledge base)

+ POLICY.md — behavior rules (escalation, dedup, retry, health thresholds)

+ LEARNINGS.md — cross-watcher patterns accumulated over time

+ clients.json — routing map: sender key -> conductor name

+

+ <name>/ — per-watcher directory (one per registered watcher)

+ meta.json — watcher registration metadata (type, created_at, expiry)

+ state.json — latest health snapshot (last_event_ts, error_count, adapter_healthy)

+ task-log.md — append-only event log (one Markdown heading per event)

+ LEARNINGS.md — per-watcher patterns (optional, watcher-specific)

+ ```

+

+ ## Files

+

+ | File | Purpose |

+ |------|---------|

+ | `CLAUDE.md` | Shared mechanism knowledge. Read by agent sessions to understand watcher infrastructure. |

+ | `POLICY.md` | Behavior rules: escalation thresholds, dedup strategy, retry backoff, health thresholds. |

+ | `LEARNINGS.md` | Cross-watcher patterns. Add entries as you notice recurring behaviors. |

+ | `clients.json` | Routing map loaded by the engine. Key format: `<adapter>:<channel>` or email address. |

+

+ ## For Agents Inspecting This Directory

+

+ To inspect watcher health and list all registered watchers:

+

+ ```bash

+ agent-deck watcher list --json

+ agent-deck watcher status <name>

+ ```

+

+ The `list --json` output includes `last_event_ts`, `error_count`, and `health_status` per watcher.

+

+ To check if a specific sender would be routed:

+

+ ```bash

+ agent-deck watcher test <name>

+ ```

+

+ ## Why This Folder Shape

+

+ Watcher state mirrors the conductor pattern (`~/.agent-deck/conductor/`) for consistency:

+ both subsystems use a singular directory root with shared top-level files and

+ per-instance subdirectories. This makes the layout predictable and tooling reusable.

+

+ The legacy `~/.agent-deck/watchers/` path is preserved as a relative compatibility

+ symlink pointing to `watcher/`. Existing tooling that reads `watchers/` continues

+ to work without modification.