policy: subagent_usage: required: true rules: - prefer sub-agents for parallelizable implementation work - use sub-agents when implementing independent roadmap items - create worktrees for sub-agents working on the same codebase - review sub-agent output before merging to main - use `agent: implementation-reviewer` for code quality checks - use `agent: qa-validator` for end-to-end validation - chain sub-agents for multi-step workflows (plan → implement → review) - always use sub-agents unless the task is trivial or requires direct interaction 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 local_first: required: true rules: - use local Docker/OrbStack before deploy - deploy only after local behavior is verified 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 development_flow: tdd: [red, orange, green] build_rule: - make build must enforce lint first - if build is green, lint is already green 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 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 compatibility: rules: - preserve shared domain compatibility across parallel worktrees - LombardPortfolio must remain available for strategy/core compatibility until intentionally removed everywhere learnings: nicegui: - ui.header must be a top-level page layout element - do not nest ui.header inside ui.column or similar containers options_page: - loading all expiries/chains before first paint can make the page appear broken - render fast first, then load incrementally nicegui_fastapi: - pages should not assume request.app.state is the right access path for shared services - prefer an explicit runtime/service registry docker_dev: - do not mount the whole repo over /app when the image contains required runtime scripts - prefer narrower mounts like ./app and ./config 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 gitea_ci: repo: base_url: "http://tea.uncloud.vpn" api_base_url: "http://tea.uncloud.vpn/api/v1" owner: "bu5hm4nn" name: "vault-dash" full_name: "bu5hm4nn/vault-dash" ssh_remote: "ssh://git@tea.uncloud.vpn:2223/bu5hm4nn/vault-dash.git" auth: preferred_method: "tea login" notes: - "`tea` is already logged in for this repo and should be preferred for API access" - "`tea api` works against this Gitea 1.25.5 instance even when higher-level `tea actions` commands are unavailable" - A raw token may exist separately, but automation should not assume one unless the user says so shell_setup: | export GITEA_URL="${GITEA_URL:-http://tea.uncloud.vpn}" export GITEA_API="${GITEA_API:-$GITEA_URL/api/v1}" export GITEA_REPO="bu5hm4nn/vault-dash" tea login list >/dev/null command -v jq >/dev/null triage: preferred_method: "use `tea api` for run/job/log discovery; use the Gitea web UI as fallback" tested_on: "2026-04-07" tested_behavior: - "`tea actions runs list` refuses to run because the server is older than 1.26.0" - "`tea api` works and authenticates via the stored tea login" - Gitea 1.25.5 exposes Actions run, job, log, workflow, artifact, and runner endpoints in swagger - The new server supports `/repos/{owner}/{repo}/actions/runs/{run}/jobs` and `/repos/{owner}/{repo}/actions/jobs/{job_id}/logs` response_shape_note: - Gitea Actions list endpoints return object wrappers such as `.workflow_runs` or `.jobs` - In jq, prefer `(.workflow_runs // .)` for runs and `(.jobs // .)` for jobs default_scope: - Prefer latest run for `git rev-parse HEAD` - If there is no run for HEAD yet, inspect the latest failed run on the current branch - If CI failed, Build and Deploy will not run because deploy is triggered after CI success query_recipes: list_recent_runs_current_branch: | branch="$(git branch --show-current)" tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/runs?branch=$branch&limit=20" | jq '(.workflow_runs // .) | map({id, workflow_id, status, event, head_branch, head_sha, created_at, html_url})' latest_run_for_head_sha: | branch="$(git branch --show-current)" sha="$(git rev-parse HEAD)" tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/runs?branch=$branch&limit=50" | jq -r --arg sha "$sha" '((.workflow_runs // .) | map(select((.head_sha // .commit_sha) == $sha)) | sort_by(.created_at // .run_started_at // .id) | reverse | .[0])' latest_failed_run_current_branch: | branch="$(git branch --show-current)" tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/runs?branch=$branch&status=failure&limit=20" | jq -r '((.workflow_runs // .) | sort_by(.created_at // .run_started_at // .id) | reverse | .[0])' list_jobs_for_run: | run_id="" tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/runs/$run_id/jobs" | jq '(.jobs // .) | map({id, name, status, conclusion, started_at, completed_at})' first_failed_job_for_run: | run_id="" tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/runs/$run_id/jobs" | jq -r '((.jobs // .) | map(select((.conclusion // .status) == "failure" or .status == "failure")) | sort_by(.started_at // .id) | .[0])' download_job_log: | job_id="" tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/jobs/$job_id/logs" viewing_job_logs: web_ui: url: "http://tea.uncloud.vpn/bu5hm4nn/vault-dash/actions" steps: - Navigate to Actions tab in the Gitea UI - Open the run from its `html_url` returned by `tea api` - Expand the failing job (lint/test/type-check/build/deploy) - Click the failed step to inspect detailed logs api: preferred_cli: "tea api" notes: - High-level `tea actions` commands may be version-gated by the CLI - "`tea api` is the stable fallback for this Gitea instance" workflows: CI: file: ".gitea/workflows/ci.yaml" jobs: [lint, type-check, test] triggers: [push main, pull_request main] Build_and_Deploy: file: ".gitea/workflows/deploy.yaml" jobs: [build, deploy] triggers: - workflow_run after CI succeeds on main - manual workflow_dispatch common_failures: missing_dependency: symptom: "ModuleNotFoundError: No module named 'X'" fix: - Add runtime deps to requirements.txt - Add dev/test tooling deps to requirements-dev.txt - CI installs requirements-dev.txt, so keep CI-critical deps there playwright_version_drift: symptom: "Playwright browser/package mismatch or local vs CI behavior differs" fix: - Keep Python Playwright pinned in requirements-dev.txt - Keep the pin aligned with `.gitea/workflows/ci.yaml` Playwright container image tag tea_version_gate: symptom: "`tea actions ...` says the server is older than 1.26.0" fix: "Use `tea api` directly against the Actions endpoints instead of high-level tea subcommands" type_error: symptom: "error: Incompatible types..." fix: "Run `mypy app/core app/models app/strategies app/services app/domain --show-error-codes --show-traceback` locally to reproduce" test_failure: symptom: "FAILED test_name" fix: "Run failing test locally with `pytest -xvs `" pre_merge_checklist: - run `pytest tests/ -v --tb=short` locally and ensure all new/changed tests pass - run `/review` to get implementation review and QA validation - verify CI passes on Gitea (lint, test, type-check, build, deploy) - address all review comments before merging to main