Avant toute tâche (fonctionnalité, bug, refactor), lire et appliquer docs/DELIVERY_WORKFLOW.md (Definition of Done). Aucune tâche n'est terminée avant que sa checklist soit complète et le CI vert (jobs lint, test, security, build, e2e de .gitea/workflows/ci.yml).

Avant de commencer

Lire docs/ROADMAP.md (travail à venir + index) et docs/ISSUES_TODOLIST.md (bugs).
Identifier ou créer l'ID stable (#NN pour une feature, BUG-NNN pour un bug — jamais réutilisé) et passer son statut à « en cours » avant de coder.

Architecture (ce qui n'est pas obvious)

Backend : FastAPI/Python 3.11, point d'entrée backend/main.py (endpoints + rendu markdown), index en mémoire (indexer.py, search.py), watcher (watcher.py), auth dans backend/auth/. Pas de base de données : JSON dans data/.
Frontend : vanilla JS zéro framework, zéro build npm (frontend/app.js, index.html, style.css). Ne pas ajouter de dépendances npm ni d'étape de build.
Desktop : Tauri (Rust) dans desktop/ ; tauri.conf.json embarque backend/** et frontend/** depuis desktop/ — les scripts de build font le staging (copie) avant cargo tauri build, sinon le build échoue.
i18n : tout texte d'interface doit exister en FR et EN (frontend/locales/fr.json + en.json).

Vérifications locales (pwsh, à faire passer avant tout commit/push)

# Backend (venv à la racine)
.\.venv\Scripts\python.exe -m pytest tests/
.\.venv\Scripts\python.exe -m ruff check backend/
.\.venv\Scripts\python.exe -m mypy backend/ --ignore-missing-imports

# Frontend : scripts Node à exécuter directement (pas de runner)
node tests/frontend/validate-imports.mjs
node tests/frontend/unit.test.mjs
# Tests JSDOM : node_modules dans tests/frontend/ (npm install là-bas si absent), ex :
node tests/frontend/pane-manager.test.mjs

# E2E (si UI touchée, ~10 min) : reproduit le job CI e2e (port 2029, auth désactivée)
npm run test:e2e                    # prérequis : uv, Node >= 20, npx playwright install chromium
bash scripts/run-e2e-local.sh -g "nom du test"   # filtre / --headed

# Windows sans bash exploitable (WSL HS, git-bash bloqué par App Control) :
npm run test:e2e:ps                 # équivalent PowerShell, mêmes conditions que le CI
pwsh -File scripts/run-e2e-local.ps1 -PlaywrightArgs @('-g','nom du test')

Un seul test backend : .\.venv\Scripts\python.exe -m pytest tests/test_search.py -q.
Sélection E2E : vérifier chaque sélecteur dans le DOM réel avant de l'utiliser dans un test ; tout test nouveau/modifié doit passer en local avant push ; pas de contournement qui masque la flakiness (waitForTimeout arbitraires, fallbacks silencieux).
La suite E2E doit finir à 100 % sans s'appuyer sur les retries. Jamais de git push avant que les 5 étapes locales soient vertes.

Version & hooks (pièges)

VERSION (racine) = source unique de vérité (SemVer), incrémenté automatiquement à chaque commit par le hook .githooks/prepare-commit-msg — feat → mineur, !: / BREAKING CHANGE → majeur, sinon correctif. Le même commit resynchronise package.json, le desktop Tauri, README.md/README.fr.md, docs/ROADMAP.md et publie la section [Unreleased] du CHANGELOG.md en [X.Y.Z] — date ; tag vX.Y.Z créé au commit, publié au push (push.followTags).
Hooks obligatoires, à installer une fois par clone : scripts/install-hooks.sh (sinon la version ne suit plus et le CI échoue via le garde-fou tests/test_version.py).
Le rattachement des fichiers de bump se fait par un --amend immédiat : le SHA affiché par git commit change — ne pas s'y fier.
Commit sans incrément (exceptionnel) : SKIP_VERSION_BUMP=1 git commit ….
Ne jamais réécrire une version déjà publiée dans le CHANGELOG ; jamais de détail dupliqué entre Roadmap et CHANGELOG.

À la fin de chaque tâche (obligatoire)

Tests unitaires ajoutés/mis à jour (correctif sans test de non-régression = pas terminé).
Toutes les vérifications locales ci-dessus vertes (E2E si UI).
Documentation mise à jour : CHANGELOG.md ([Unreleased]), docs/ROADMAP.md (statut + index), fiche docs/features/ ou docs/archive/, docs/ISSUES_TODOLIST.md (si bug), guide utilisateur i18n FR/EN + README si impact utilisateur, docstrings + response_model si API.
Commit conventionnel référençant l'ID (feat: … #12), puis push et CI vert.

Cartographie documentaire

Sujet	Fichier
Méthode de livraison / DoD	`docs/DELIVERY_WORKFLOW.md`
Version livrée (source unique)	`VERSION` + `scripts/bump_version.py`
Travail à venir + index	`docs/ROADMAP.md`
Historique des versions	`CHANGELOG.md`
Conception par feature	`docs/features/<slug>.md`
Guides d'utilisation	`docs/GUIDES/`
Archive du complété	`docs/archive/COMPLETED_v1-v2.md`
Bugs / TODO	`docs/ISSUES_TODOLIST.md`
Build & releases	`docs/DEVELOPMENT_AND_RELEASES.md`
Standards de code	`docs/CONTRIBUTING.md`

Conventions

Commits : type: description — feat, fix, perf, refactor, docs, style, chore, test.
Sécurité : tout chemin fichier fourni par l'utilisateur passe par _resolve_safe_path().
Ne jamais committer de secrets, clés ou tokens (.env jamais committé ; secrets dans data/api_keys.json ou variables OBSIGATE_*).
Respecter le style du code existant (ruff/mypy 0 erreur ; CSS variables, pas de couleurs hardcodées ; safeCreateIcons() plutôt que lucide.createIcons() direct).

5.9 KiB Raw Permalink Blame History

AGENTS.md — Instructions obligatoires du dépôt ObsiGate

Règle n°1 — Méthode de livraison unique