786953c403
Verified: - Web UI URL for viewing workflow runs - SSH command to access runner logs - Common failure patterns and fixes
115 lines
4.1 KiB
Markdown
115 lines
4.1 KiB
Markdown
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
|
|
|
|
forgejo_ci:
|
|
viewing_job_logs:
|
|
web_ui:
|
|
url: "http://git.uncloud.vpn:3000/bu5hm4nn/vault-dash/actions"
|
|
steps:
|
|
- Navigate to Actions tab in Forgejo UI (VPN access required)
|
|
- Click on the workflow run to see job status
|
|
- Expand failing job (lint/test/type-check/build/deploy)
|
|
- Click on failed step to see detailed logs
|
|
runner_logs:
|
|
ssh: "ssh root@5.75.141.4"
|
|
command: "docker logs forgejo-runner --tail 100"
|
|
job_workspace: "/opt/forgejo-runner/data/"
|
|
common_failures:
|
|
missing_dependency:
|
|
symptom: "ModuleNotFoundError: No module named 'X'"
|
|
fix: "Add package to requirements.txt AND .forgejo/workflows/deploy.yaml (test + type-check jobs)"
|
|
type_error:
|
|
symptom: "error: Incompatible types..."
|
|
fix: "Run `mypy app --ignore-missing-imports` locally to reproduce"
|
|
test_failure:
|
|
symptom: "FAILED test_name"
|
|
fix: "Run failing test locally with pytest -xvs"
|