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.**
+  confidence:
-   - Do not stop after code changes.
+    rules:
-   - Run the app locally.
+      - browser-visible behavior beats log-only confidence
-   - Run real tests against the running app.
+      - do not treat returned HTML as success if the page still has runtime/UI errors
-   - For UI work, prefer real browser tests (Playwright) over assumptions.
+      - do not claim a feature is live unless the rendered UI consumes it
-   - Verify the exact route/page that changed.
 
-2. **Local Docker first, deploy later.**
+  development_flow:
-   - Use local Docker/OrbStack for fast feedback.
+    tdd: [red, orange, green]
-   - Only deploy after local behavior is verified.
+    build_rule:
+      - make build must enforce lint first
+      - if build is green, lint is already green
 
-3. **Browser-visible behavior beats log-only confidence.**
+  review:
-   - A route returning HTML is not sufficient.
+    required_before_merge: true
-   - Confirm page content renders and no runtime/500 error is visible.
+    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.**
+  backlog:
-   - New feature branches must not silently remove compatibility types used elsewhere.
+    review_after_each_sprint: true
-   - In this project, `LombardPortfolio` is still required by strategy/core modules.
+    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.**
+  compatibility:
-   - Backend service existence is not enough.
+    rules:
-   - The rendered page must actually consume the live data path.
+      - 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.**
+learnings:
-   - Start by making the failure visible with a test or reproducible check (Red).
+  nicegui:
-   - Iterate toward partial progress while keeping the failure scoped and observable (Orange).
+    - ui.header must be a top-level page layout element
-   - Finish only when the behavior is implemented and the test loop passes cleanly (Green).
+    - do not nest ui.header inside ui.column or similar containers
 
-7. **Linting is part of the build, not an optional extra step.**
+  options_page:
-   - `make build` must enforce linting first.
+    - loading all expiries/chains before first paint can make the page appear broken
-   - Do not treat lint as a separate, skippable preflight.
+    - render fast first, then load incrementally
-   - If the build is green, lint must already be green.
 
-8. **Run the `/review` skill before merging worktrees back.**
+  nicegui_fastapi:
-   - Any worktree/sub-agent implementation must go through `/review` before integration to `main`.
+    - pages should not assume request.app.state is the right access path for shared services
-   - Do not merge worktree changes back based only on compile/test results.
+    - prefer an explicit runtime/service registry
-   - Review first, then integrate.
 
-9. **Review the backlog after each sprint.**
+  docker_dev:
-   - After each completed sprint or merged feature slice, review `docs/roadmap/ROADMAP.yaml` and the per-task YAML files.
+    - do not mount the whole repo over /app when the image contains required runtime scripts
-   - Add any new backlog items uncovered during implementation, testing, review, or deployment.
+    - prefer narrower mounts like ./app and ./config
-   - Reorder priorities and update dependencies based on new knowledge.
-   - Capture follow-up work explicitly instead of relying on memory or chat context.
 
-## Project Learnings
+validation_checklist:
-
+  - local Docker stack starts cleanly
-### NiceGUI layout constraint
+  - /health returns OK
-- `ui.header()` must be a top-level page layout element.
+  - changed page opens in browser automation
-- Do not nest `ui.header()` inside `ui.column()` or other containers.
+  - no visible 500/runtime error
-
+  - screenshot artifact captured when useful
-### Options page performance lesson
+  - relevant logs checked
-- 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