docs: compact agent policy into yaml

AGENTS.md

@@ -1,73 +1,78 @@
-# AGENTS.md
+policy:
+  test_loop:
+    required: true
+    rules:
+      - run the app locally after changes
+      - run real tests against the running app
+      - for UI work, prefer Playwright/browser-visible checks
+      - verify the exact changed route/page
 
-## Engineering Rules
+  local_first:
+    required: true
+    rules:
+      - use local Docker/OrbStack before deploy
+      - deploy only after local behavior is verified
 
-1. **Always close the test loop.**
-   - Do not stop after code changes.
-   - Run the app locally.
-   - Run real tests against the running app.
-   - For UI work, prefer real browser tests (Playwright) over assumptions.
-   - Verify the exact route/page that changed.
+  confidence:
+    rules:
+      - browser-visible behavior beats log-only confidence
+      - do not treat returned HTML as success if the page still has runtime/UI errors
+      - do not claim a feature is live unless the rendered UI consumes it
 
-2. **Local Docker first, deploy later.**
-   - Use local Docker/OrbStack for fast feedback.
-   - Only deploy after local behavior is verified.
+  development_flow:
+    tdd: [red, orange, green]
+    build_rule:
+      - make build must enforce lint first
+      - if build is green, lint is already green
 
-3. **Browser-visible behavior beats log-only confidence.**
-   - A route returning HTML is not sufficient.
-   - Confirm page content renders and no runtime/500 error is visible.
+  review:
+    required_before_merge: true
+    install_tool: review_install_agents
+    rules:
+      - install review agents with the review_install_agents tool before running the review workflow if needed
+      - use the full parallel review flow before merging worktree or sub-agent changes to main
+      - do not merge based only on compile/test results
 
-4. **When using parallel worktrees, preserve shared domain models.**
-   - New feature branches must not silently remove compatibility types used elsewhere.
-   - In this project, `LombardPortfolio` is still required by strategy/core modules.
+  backlog:
+    review_after_each_sprint: true
+    source_of_truth:
+      - docs/roadmap/ROADMAP.yaml
+      - docs/roadmap/backlog
+      - docs/roadmap/in-progress
+      - docs/roadmap/done
+      - docs/roadmap/blocked
+      - docs/roadmap/cancelled
+    rules:
+      - add newly discovered backlog items
+      - reorder priorities and dependencies based on new knowledge
+      - capture follow-up work explicitly
 
-5. **Do not claim a feature is live unless the UI is wired to it.**
-   - Backend service existence is not enough.
-   - The rendered page must actually consume the live data path.
+  compatibility:
+    rules:
+      - preserve shared domain compatibility across parallel worktrees
+      - LombardPortfolio must remain available for strategy/core compatibility until intentionally removed everywhere
 
-6. **Always work with TDD principles: Red, Orange, Green.**
-   - Start by making the failure visible with a test or reproducible check (Red).
-   - Iterate toward partial progress while keeping the failure scoped and observable (Orange).
-   - Finish only when the behavior is implemented and the test loop passes cleanly (Green).
+learnings:
+  nicegui:
+    - ui.header must be a top-level page layout element
+    - do not nest ui.header inside ui.column or similar containers
 
-7. **Linting is part of the build, not an optional extra step.**
-   - `make build` must enforce linting first.
-   - Do not treat lint as a separate, skippable preflight.
-   - If the build is green, lint must already be green.
+  options_page:
+    - loading all expiries/chains before first paint can make the page appear broken
+    - render fast first, then load incrementally
 
-8. **Run the `/review` skill before merging worktrees back.**
-   - Any worktree/sub-agent implementation must go through `/review` before integration to `main`.
-   - Do not merge worktree changes back based only on compile/test results.
-   - Review first, then integrate.
+  nicegui_fastapi:
+    - pages should not assume request.app.state is the right access path for shared services
+    - prefer an explicit runtime/service registry
 
-9. **Review the backlog after each sprint.**
-   - After each completed sprint or merged feature slice, review `docs/roadmap/ROADMAP.yaml` and the per-task YAML files.
-   - Add any new backlog items uncovered during implementation, testing, review, or deployment.
-   - Reorder priorities and update dependencies based on new knowledge.
-   - Capture follow-up work explicitly instead of relying on memory or chat context.
+  docker_dev:
+    - do not mount the whole repo over /app when the image contains required runtime scripts
+    - prefer narrower mounts like ./app and ./config
 
-## Project Learnings
-
-### NiceGUI layout constraint
-- `ui.header()` must be a top-level page layout element.
-- Do not nest `ui.header()` inside `ui.column()` or other containers.
-
-### Options page performance lesson
-- Loading all expiries/chains before first paint can make the page appear broken.
-- Prefer rendering fast, then loading data incrementally.
-
-### FastAPI/NiceGUI integration lesson
-- NiceGUI page handlers should not assume `request.app.state.*` is always the right access path for shared services.
-- Use an explicit runtime/service registry if needed.
-
-### Docker development lesson
-- Avoid mounting the whole repo over `/app` when the image contains required runtime scripts.
-- Mount narrower paths in dev (`./app`, `./config`) to preserve image-managed files like entrypoints.
-
-## Validation Checklist for UI Changes
-- [ ] Local Docker stack starts cleanly
-- [ ] `/health` returns OK
-- [ ] Changed page opens in browser automation
-- [ ] No visible 500/runtime error
-- [ ] Screenshot artifact captured
-- [ ] Relevant logs checked
+validation_checklist:
+  - local Docker stack starts cleanly
+  - /health returns OK
+  - changed page opens in browser automation
+  - no visible 500/runtime error
+  - screenshot artifact captured when useful
+  - relevant logs checked