pmomusic/Blackboard/Rules.md

Règles de développement PMOMusic

Contexte projet

PMOMusic : Système audio HiFi basé sur UPnP/DLNA (LossLess/Bit-Perfect uniquement).

Technologies :

• Backend : Rust
• Frontend : Vue.js (TypeScript/JavaScript)

Composants : Media Server, Control Point, Media Renderer

Développement : Collaboration humain-LLM (Claude/ChatGPT/Ollama)

---

Règles Rust (Cargo workspace)

Gestion des dépendances

⚠️ OBLIGATOIRE : Les dépendances doivent être ajoutées au niveau workspace autant que possible.

1. Ajouter la dépendance dans Cargo.toml racine (section [workspace.dependencies])
2. Référencer avec { workspace = true } dans le Cargo.toml de la crate

Exemple :

# Cargo.toml (racine workspace)
[workspace.dependencies]
rand = "0.9"

# pmocontrol/Cargo.toml
[dependencies]
rand = { workspace = true }

Exceptions : Dépendances spécifiques à une seule crate avec version très particulière.

---

Prérequis des tâches

Spécification des crates cibles

⚠️ CRITIQUE : Le LLM doit REFUSER d'exécuter une tâche si la ou les crates concernées ne sont pas explicitement spécifiées dans le fichier Todo/{nom}.md.

Informations requises :

• Nom de la ou des crates à modifier
• Chemin relatif si nécessaire (ex: pmocontrol/src/...)

En cas d'absence :

• Le LLM demande clarification à l'humain
• Ne pas deviner ou supposer les crates concernées

---

Workflow Blackboard

Structure

Blackboard/
├── ToThinkAbout/    # Réflexion, idées, architecture
├── Architecture/    # Documentation d'architecture validée
├── Todo/            # Tâches à réaliser
├── Report/          # Rapports de tâches réalisées
├── ToDiscuss/       # Tâches incomplètes nécessitant discussion
├── Done/            # Tâches terminées (synthèses)
└── Rules.md         # Ce fichier

Cycle de vie d'une tâche

flowchart LR
    THINK[ToThinkAbout] -->|Spécification| TODO[Todo]
    TODO -->|Implémentation| REPORT[Report]
    REPORT -->|Humain décide| DONE[Done]
    REPORT -->|Humain décide| DISCUSS[ToDiscuss]
    DISCUSS -->|Reprise travail| REPORT

Règles strictes

1. Phase de réflexion (ToThinkAbout)

• Collaboration : Humain et LLM peuvent modifier
• But : Explorer idées, définir architecture
• Sortie : Documents de spécification → Todo/

2. Phase de réalisation (Todo → Report)

• Input : Fichier Todo/{nom}.md

• Action : LLM implémente la tâche

• Output : Fichier Report/{nom}.md (même nom obligatoire)

• Contenu du rapport :

  • Résumé court du travail effectué (2-3 phrases maximum)
  • Liste exhaustive des fichiers créés/modifiés avec leur chemin complet
  • INTERDIT : Rapport détaillé dans la discussion (uniquement dans Report/)
  • INTERDIT : Explication technique détaillée, code d'exemple, architecture

• Réponse dans la discussion (après implémentation) :

  • Message très bref confirmant la fin de la tâche
  • Référence au fichier Report/{nom}.md pour les détails
  • Format attendu : "Tâche terminée. Voir Report/{nom}.md pour la liste des modifications."
  • PAS de : résumé détaillé, explication du code, liste des avantages, etc.

3. Décision humaine (Report → Done ou ToDiscuss)

⚠️ CRITIQUE : Seul l'humain décide de la destination. Le LLM ne doit JAMAIS déplacer ou classer une tâche.

Cas 1 : Tâche complète → Done/

• Humain déplace Todo/{nom}.md → Done/{nom}.md
• LLM crée une synthèse (tâche originale + rapport)
• Contenu final dans Done/{nom}.md

Cas 2 : Tâche incomplète → ToDiscuss/

• Humain déplace Todo/{nom}.md → ToDiscuss/{nom}.md
• Humain ajoute annotations/remarques dans ToDiscuss/{nom}.md
• Lors de la reprise :
  • LLM lit les annotations
  • Complète Report/{nom}.md avec les modifications
  • Nouveau cycle de validation

4. Documentation architecture (Architecture/)

• Contient les documents d'architecture validés et stables
• Référence pour patterns de code (ex: pmoconfig_ext.md, pmoserver_ext.md)
• Ne pas modifier sans validation explicite

---

Versioning (Jujutsu)

Système : Jujutsu (jj)
Repository : https://gargoton.petite-maison-orange.fr/eric/pmomusic.git

Commandes Makefile

Commande	Action	Description
make jjnew	Nouveau commit	Documente le commit actuel (jj auto-describe) puis jj new
make jjpush	Push vers Git	Documente le commit puis jj git push --change @ → Crée branche + PR sur le serveur
make jjfetch	Récupération	jj git fetch puis jj new main@origin → Après validation du PR

Gestion version

• Source de vérité : PMOMusic/Cargo.toml
• Sync : version.txt (généré par Makefile)
• Incrémentation : make bump-version (avant jjpush)

---

Checklist LLM

Avant de commencer une tâche

• Lire Todo/{nom}.md
• Vérifier les références à Architecture/ si mentionnées
• Comprendre les contraintes (HiFi, LossLess, UPnP/DLNA)

Pendant la réalisation

• Suivre les patterns d'architecture existants
• Utiliser Rust (backend) ou Vue.js/TypeScript (frontend)
• Tester le code si applicable

Après la réalisation

• Créer Report/{nom}.md (même nom que la tâche)
• Lister fichiers créés/modifiés
• NE PAS déplacer la tâche
• NE PAS écrire de rapport détaillé dans la discussion
• Attendre la décision humaine

Si tâche en ToDiscuss

• Lire annotations ajoutées par l'humain
• Expliquer dans Report/{nom}.md comment les remarques sont prises en compte
• Reprise du cycle de validation

---

Diagrammes Mermaid

Tous les diagrammes d'architecture doivent utiliser Mermaid. La commande make blackboard-html génère une version HTML consultable avec rendu des diagrammes.

Syntaxe stricte :

• Labels de subgraph : subgraph Name[Label] (pas de guillemets doubles)
• Balises HTML : Node["Text<br/>Multi"] (guillemets doubles)
• Formes spéciales : DB[("database")], Decision{"Question?"} (guillemets)