[doctor] missing_tool_artifacts sur les sous-roots d'un workspace : comportement voulu ou faux positif ?

[SmilosNIJ]

Contexte

En mode workspace, Studio appelle diagnose(root) sur le sous-root actif (ex. clients/dupont-conseil), pas sur la racine du workspace. Si ce sous-root n'a pas de CLAUDE.md, Doctor émet missing_tool_artifacts.

Reproduire avec exemples/agence-multi-clients :

node .ai/base.mjs studio --root exemples/agence-multi-clients

→ signal missing_tool_artifacts sur clients/dupont-conseil et clients/martin-digital, même si exemples/agence-multi-clients/CLAUDE.md existe.

Question de spec

La doc (docs/guides/connecter-votre-outil.md, docs/start/installer-claude-code.md) dit que CLAUDE.md doit être «à la racine du dossier ouvert dans l'outil». Dans un workspace, ce dossier est la racine du workspace — pas chaque sous-root.

Est-ce qu'un sous-root d'un workspace doit porter son propre CLAUDE.md ?

• Si oui : base init devrait le proposer pour chaque sous-root (aujourd'hui il ne le fait pas), et le signal Doctor est légitime.
• Si non : Doctor devrait, en mode workspace, ne vérifier missing_tool_artifacts qu'à la racine du workspace, et émettre silence sur les sous-roots.

Code concerné

• tools/doctor/diagnose.mjs:187 — vérifie paths.has("CLAUDE.md") sur le root passé, sans savoir s'il est sous-root d'un workspace.
• tools/studio/server.mjs:241 — diagnose(rootOf()) : rootOf() retourne le sous-root actif.

Suggestion

Clarifier dans la spec (FR-DOCTOR-001 ou FR-INIT-002) si missing_tool_artifacts s'applique aux sous-roots d'un workspace, et aligner Doctor + base init en conséquence. Si la réponse est «non», supprimer le signal sur les sous-roots et documenter que le CLAUDE.md de la racine du workspace suffit.

---

Découvert en parcourant le tutoriel Équipe Module 2 sur exemples/agence-multi-clients.

[cbardyn]

Bonjour Nicolas, merci pour ce signalement: les renvois au code sont justes et la question de fond est la bonne.

Une précision d'abord, sur la reproduction: en l'état du dépôt, exemples/agence-multi-clients ne contient aucun CLAUDE.md, ni à la racine du workspace ni dans les sous-roots. Le missing_tool_artifacts que vous observez ne contredit donc pas un CLAUDE.md de workspace existant: il n'y en a pas. La prémisse «même si le CLAUDE.md du workspace existe» ne tient pas ici.

Sur le fond, notre lecture est que le signal est légitime, et que ce n'est pas un faux positif. Un workspace n'agrège pas des sous-dossiers quelconques: la détection ne classe en collection que des sous-dossiers qui sont eux-mêmes des roots BASE complets (chacun avec son .ai/agents/<id>/AGENT.md). Le base.workspace.json ne fait que les fédérer; chaque sous-root reste un root autonome. Et c'est bien le sous-root que l'outil ouvre réellement (Studio diagnostique le sous-root actif, default: true). Un root qu'un outil agentique va ouvrir sans CLAUDE.md manque effectivement son point d'entrée: c'est précisément ce que le signal veut dire. Réponse à votre question, donc: oui, un sous-root devrait porter son propre CLAUDE.md.

Là où vous avez parfaitement raison, c'est sur l'incohérence: base init sur un collection n'écrit aujourd'hui que le base.workspace.json et ne propose pas les artefacts outil par sous-root (FR-INIT-002). Doctor réclame donc un CLAUDE.md que init ne sait pas créer à cet endroit. Et la doc («à la racine du dossier ouvert») gagnerait à dire qu'en mode workspace ce dossier est le sous-root.

Le correctif que nous envisageons va donc côté init et doc, pas côté doctor: étendre le plan d'init pour proposer (création seule, sans rien écraser) les artefacts manquants de chaque sous-root, et préciser ce point dans installer-claude-code.md et connecter-votre-outil.md. Nous tranchons cela par une décision écrite avant de toucher la spec. Si l'envie vous prend d'ouvrir la PR sur le volet init, elle sera la bienvenue: pensez au Signed-off-by (DCO) et à un renvoi à FR-INIT-002. Merci encore.

[cbardyn]

Bonjour Nicolas, un mot après la 1.2.0.

Vous demandiez si le missing_tool_artifacts sur les sous-racines était un faux positif. La réponse tient, le signal visait juste, et l'exemple l'incarne maintenant: agence-multi-clients porte un CLAUDE.md par sous-racine, et base doctor n'y signale plus rien. Il manquait les fichiers, pas la règle.

La suite côté init (faut-il qu'il crée ces artefacts par sous-racine) se joue dans #12; on la garde ouverte là-bas. Merci encore pour le renvoi au code, il était juste.