ducoterra
fcac876d40
**Phase 134 final verification pass — all green** (all 3 task files already in `complete/`; no implementation was missing) - Verified: 5-state `SyncStatus` + `cancelled` terminal (error None, final counts kept), `POST /api/sync/cancel` (202/409/403), cooperative `_check_cancelled` boundaries, shutdown `CancelledError` contract preserved, `#sync-cancel-btn` show/hide + neutral "Sync cancelled" settle, 8-branch poll tree, re-attach — code, unit, integration, and E2E layers all present - `uv run pytest --cov=app --cov-report=term-missing` → **3150 passed**, `app/` coverage **99%** (gate: >90%) - `uv run pytest tests/e2e/test_sync_cancel.py -v --no-cov` (isolated) → **3 passed** (47.6 s) - `uv run ruff check .` → clean; `uv run pyright` → 0 errors, 0 warnings **Completion criteria:** ① cancel endpoint 202/409/403 ✅ (unit + E2E) ② `cancelled` terminal reported by status, error null, counts kept ✅ (integration `test_cancel_mid_run_lands_in_cancelled_then_resyncs_clean`) ③ unrequested-cancel pin ✅ (`test_unrequested_cancel_is_never_swallowed_and_never_converts`) ④ UI lifecycle + clean re-sync (sentinel row, full 40-file import) ✅ (E2E) ⑤ suite/coverage/E2E gates ✅ ⑥ uncancelled runs byte-identical ✅ (all 3150 pre-existing tests green untouched) - Docs: README.md reviewed in full against code (pages, auth endpoints, every config default vs `app/config.py`, palette 9+8, fail-loud, cancel section) — consistent, no changes needed. AGENTS.md: fixed one pre-existing inaccuracy (rule 2 "move its file" → "move its directory" — phases are directories); everything else verified accurate - No live infrastructure touched; no deviations **Next pending phase:** `135_git_source_branch`
56 lines
3.3 KiB
Markdown
56 lines
3.3 KiB
Markdown
# AGENTS.md — Operating Rules for All Agents on This Repo
|
|
|
|
1. **Always read `.agents/PLAN.md` first.** It contains the architecture, the
|
|
LOCKED DECISIONS, the UI/UX standards, the data model, and the roadmap.
|
|
Do not design anything that contradicts it.
|
|
2. **Follow the phased execution protocol in `.agents/phases/`.** Work through
|
|
`.agents/phases/todo/` in numeric order. When a phase is complete, move its
|
|
directory to `.agents/phases/complete/`.
|
|
3. **Strictly adhere to the LOCKED DECISIONS** (PLAN §2). If you believe a
|
|
LOCKED decision is wrong, stop and flag it — do not silently deviate.
|
|
4. **"One Story, One Phase":** each user story in `.agents/user_stories/`
|
|
corresponds to a distinct execution phase that includes its own dedicated
|
|
Playwright E2E test suite (one test file per story, run in isolation).
|
|
5. **"UI Structure Check":** before finalizing any UI component, verify that
|
|
it follows the layout principles in `.agents/PLAN.md` §7 (proper container
|
|
usage, the 72rem centered reading column — every page rides the 72rem
|
|
container at every viewport; phase 100 supersedes §7.1's 46rem chat
|
|
column, full-width tables on Sources — no skinny wasted-space lists) and
|
|
meets WCAG 2.1 AA basics (semantic
|
|
landmarks, labels, contrast ≥4.5:1, focus-visible, aria-live for the
|
|
stream).
|
|
6. **"No CDN Rule":** all CSS, JS, fonts, and images must be served statically
|
|
from within the FastAPI application. No `<script src="https://…">` or
|
|
`<link href="https://…">` tags in HTML templates unless bundled locally.
|
|
An integration test enforces this on the index page.
|
|
7. **"Debugpy Check":** any new entrypoint must keep the conditional import —
|
|
`debugpy` is imported **only** when `DEBUGPY=1` (see
|
|
`app/core/debugging.py`); default off, never imported otherwise.
|
|
8. **Git protocol:** Git is mandatory. One **atomic, professional commit per
|
|
completed phase** (Conventional Commits, e.g. `feat(rag): stream RAG
|
|
answers over SSE with source citations`). Always append `--no-gpg-sign`
|
|
(the repo also sets `commit.gpgsign=false`). `.agents/` is **tracked and
|
|
committed** with the phase — only runtime artifacts (`.agents/phase-sessions/`,
|
|
`.agents/pipeline.log`) are gitignored.
|
|
9. **Test gates are non-negotiable:** a phase is complete only when unit +
|
|
integration tests pass, `app/` coverage is **>90%**
|
|
(`uv run pytest --cov=app --cov-report=term-missing`), and the phase's
|
|
Playwright E2E file passes **in isolation**
|
|
(`uv run pytest tests/e2e/test_<story>.py -v --no-cov`).
|
|
10. **Amply log, visibly feed back:** server-side, log the required
|
|
per-turn line (PLAN §9); UI-side, honor the "never stale" feedback
|
|
contract (PLAN §7.4).
|
|
|
|
## Quick reference
|
|
```bash
|
|
podman compose up -d db # start Postgres 17 + pgvector
|
|
cp .env.example .env # once; then edit
|
|
uv run alembic upgrade head # apply migrations
|
|
uv run uvicorn app.main:app --reload # dev server (add DEBUGPY=1 to debug)
|
|
uv run pytest # unit + integration
|
|
uv run pytest --cov=app --cov-report=term-missing
|
|
uv run playwright install chromium # once
|
|
uv run pytest tests/e2e/test_smoke.py -v --no-cov
|
|
uv run ruff check . && uv run pyright # lint + types
|
|
```
|