new advisories

AGENTS.md

@@ -329,7 +329,7 @@ If no design decision is required, you proceed autonomously, implementing the ch
 
 ---
 
-### 5) Working Agreement (Global)
+### 5) Working Agreement (Global)
 
 1. **Task status discipline**
 
@@ -352,10 +352,41 @@ If no design decision is required, you proceed autonomously, implementing the ch
 5. **Completion**
 
    * When you complete all tasks in scope for your current instruction set, explicitly state that you are done with those tasks.
-6. **AGENTS.md discipline**
-   * Project / technical managers ensure each module’s `AGENTS.md` exists, is up to date, and reflects current design and advisory decisions.
-   * Implementers must read and follow the relevant `AGENTS.md` before coding in a module.
-   * If a mismatch or gap is found, implementers log it via `BLOCKED` status and the sprint’s **Decisions & Risks**, and then continue with other work instead of asking for live clarification.
+6. **AGENTS.md discipline**
+   * Project / technical managers ensure each module’s `AGENTS.md` exists, is up to date, and reflects current design and advisory decisions.
+   * Implementers must read and follow the relevant `AGENTS.md` before coding in a module.
+   * If a mismatch or gap is found, implementers log it via `BLOCKED` status and the sprint’s **Decisions & Risks**, and then continue with other work instead of asking for live clarification.
+
+---
+
+### 7) Advisory Handling (do this every time a new advisory lands)
+
+**Trigger:** Any new or updated file under `docs/product-advisories/` (including archived) automatically starts this workflow. No chat approval required.
+
+1) **Doc sync (must happen for every advisory):**
+   - Create/update **two layers**:
+     - **High-level**: `docs/` (vision/key-features/market) to capture the moat/positioning and the headline promise.
+     - **Detailed**: closest deep area (`docs/reachability/*`, `docs/market/*`, `docs/benchmarks/*`, `docs/modules/<module>/*`, etc.).
+   - **Code & samples:**
+     - Inline only short fragments (≤ ~20 lines) directly in the updated doc for readability.
+     - Place runnable or longer samples/harnesses in `docs/benchmarks/**` or `tests/**` with deterministic, offline-friendly defaults (no network, fixed seeds), and link to them from the doc.
+     - If the advisory already contains code, carry it over verbatim into the benchmark/test file (with minor formatting only); don’t paraphrase away executable value.
+   - **Cross-links:** whenever moats/positioning change, add links from `docs/07_HIGH_LEVEL_ARCHITECTURE.md`, `docs/key-features.md`, and the relevant module dossier(s).
+
+2) **Sprint sync (must happen for every advisory):**
+   - Add Delivery Tracker rows in the relevant `SPRINT_*.md` with owners, deps, and doc paths; add an Execution Log entry for the change.
+   - If code/bench/dataset work is implied, create tasks and point to the new benchmark/test paths; add risks/interlocks for schema/feed freeze or transparency caps as needed.
+
+3) **De-duplication:**
+   - Check `docs/product-advisories/archived/` for overlaps. If similar, mark “supersedes/extends <advisory>` in the new doc and avoid duplicate tasks.
+
+4) **Defaults to apply (unless advisory overrides):**
+   - Hybrid reachability posture: graph DSSE mandatory; edge-bundle DSSE optional/targeted; deterministic outputs only.
+   - Offline-friendly benches/tests; frozen feeds; deterministic ordering/hashes.
+
+5) **Do not defer:** Execute steps 1–4 immediately; reporting is after the fact, not a gating step.
+
+**Lessons baked in:** Past delays came from missing code carry-over and missing sprint tasks. Always move advisory code into benchmarks/tests and open the corresponding sprint rows the same session you read the advisory.
 ---
 
 ### 6) Role Switching