Aussi en: English, Español, Português, 日本語, Deutsch · Tous les guides en français
Transparence : nous développons Carbon Forge chez 100monkeys.ai ; lisez donc ceci comme le récit du fabricant. Ce guide a été rédigé par l'un de nos agents d'IA à partir de la documentation publique, principalement les sections symbols.drift et Governed seams de MCP tools catalog: Semantics et « Drift between prose and code » dans The Carbon paradigm, et relu par l'entreprise ; cette version française est une traduction du guide original en anglais. Le tableau et les appels sont les exemples de la documentation elle-même ; les citations restent en anglais avec la traduction à côté. Là où la documentation laisse une question ouverte, la dernière section le dit.
Ce qu'est le rapport
La page du paradigme en une ligne : "A workspace's reserved .governed-seams page declares which pages govern which definitions of a code tree" (la page réservée .governed-seams d'un workspace déclare quelles pages gouvernent quelles définitions d'un arbre de code). symbols.drift "joins every definition a lane adds, removes or re-signs to the seams that govern it and reports each as changed with or without a patch to its governing page on the same lane, from the syntax index alone, so the same lane and the same seams page answer the same report byte for byte." (relie chaque définition qu'une lane ajoute, supprime ou dont elle change la signature aux seams qui la gouvernent, et signale chacune comme modifiée avec ou sans patch sur sa page gouvernante dans la même lane, à partir du seul index syntaxique ; la même lane et la même page de seams donnent le même rapport octet pour octet.) Aucun modèle ne lit quoi que ce soit. Et une limite à garder en tête : "The report advises and never refuses a landing." (Le rapport conseille et ne refuse jamais une intégration.)
Étape 1. Choisir les définitions qu'une page décrit
Commencez par les pages qui tromperaient le lecteur si le code bougeait sous elles : une page d'architecture sur la facturation, un guide sur la connexion. Trouvez les définitions qu'elles décrivent avec l'index sémantique :
symbols.search { "tree": "app", "query": "charge", "prefix": true }Les définitions viennent des requêtes de tags de tree-sitter pour TypeScript et TSX, JavaScript, Python, Go, Rust, C, C++, C#, Java, Ruby, PHP, Scala et Bash. CSS, HTML, JSON, YAML, TOML et HCL ont des arbres syntaxiques "but no definitions or references" (mais ni définitions ni références) ; un seam sur ces fichiers ne signale donc rien. Les noms sont "matched by name, not by type checking" (rapprochés par leur nom, pas par vérification de types).
Étape 2. Écrire la page .governed-seams
Créez une page au chemin réservé .governed-seams dont le premier tableau Markdown a pour en-tête tree | glob | symbols | records. L'exemple de la documentation :
| tree | glob | symbols | records |
| --- | --- | --- | --- |
| app | src/billing/** | chargeCard, refund | architecture/billing |
| app | src/auth/*.ts | * | guides/login, architecture/security |tree: le chemin d'un arbre de code.glob: une règle dans la syntaxe des règles d'exclusion de l'import, sur les chemins de fichiers de l'arbre, ne commençant pas par!.symbols: des noms de définitions séparés par des virgules, ou*seul pour toutes les définitions sous le glob.records: des chemins de pages séparés par des virgules, les pages qui gouvernent ces définitions.
"A seam is declared, never inferred: no link, tag, metadata key or embedding makes one." (Un seam est déclaré, jamais déduit : aucun lien, tag, clé de métadonnées ou embedding n'en crée un.) La page est lue depuis le trunk, "so a lane cannot ungovern its own change." (si bien qu'une lane ne peut pas soustraire son propre changement à la gouvernance.) Intégrez-la sur le trunk avant le travail qu'elle doit surveiller. Une page mal formée bloque tous les rapports jusqu'à sa correction, avec une phrase qui nomme la ligne : The governed seams page .governed-seams is malformed at line <n>, ...
Étape 3. Modifier du code gouverné sur une lane
Le rapport lit une lane, donc le changement doit s'y trouver : lanes.create, puis trees.apply_patch ou trees.put avec lane, comme le montre Working in lanes. Changez par exemple la signature de chargeCard en ajoutant un paramètre.
Étape 4. Lire le rapport de dérive
symbols.drift { "lane": "agent/7/fix-login" }Ajoutez tree pour ne lire qu'un arbre. La réponse :
{ lane, composition_hash, report_sha256, findings, pending, governed_rows }Chaque constat nomme le tree, le path, le symbol et le kind, la from_signature sur le trunk et la to_signature sur la lane (null quand un côté ne la contient pas), records sous la forme { path, updated_on_lane }, et callers, le nombre de références au nom sur la lane. La class est le verdict : seam_changed_without_record quand la lane ne porte aucun patch actif sur une page gouvernante. C'est votre doc obsolète, repérée avant l'intégration.
Lisez pending avant de vous fier à un rapport vide : il liste les fichiers modifiés sous le glob d'un seam auxquels l'index "cannot answer yet" (ne peut pas encore répondre), et "the report is complete when pending is empty." (le rapport est complet quand pending est vide.) Une lane en conflit est refusée jusqu'à la résolution du conflit.
Étape 5. Mettre à jour la page qui gouverne, sur la même lane
Modifiez architecture/billing avec pages.apply_patch et la même lane, pour que la page et le code attendent ensemble. Le guide Land a code change and its documentation in one changeset (en anglais) détaille cette partie.
Étape 6. Relire le rapport, puis intégrer
Relancez symbols.drift. Le constat indique maintenant seam_changed_with_record, et son record affiche updated_on_lane. Gardez le rapport avec la revue : composition_hash est le hash de la composition de lane qu'il a lue, et report_sha256 couvre le texte canonique du rapport, "so a report is bound to the exact change it read." (si bien qu'un rapport est lié au changement exact qu'il a lu.) Un patch ultérieur change les deux. Intégrez ensuite la lane en un seul changeset.
Comme le rapport ne fait que conseiller, l'application des règles vous revient. Un modèle, le nôtre et non celui de la documentation : sur un trunk protégé, nommez le glob du code gouverné dans .landing-rules avec la personne responsable de la page gouvernante comme approbatrice, et faites-lui lire d'abord le rapport de dérive.
Ce que la documentation laisse sans réponse
- Qui peut écrire
.governed-seams. La documentation réserve.landing-rulesaux admins ; pour la page des seams, elle dit seulement qu'elle est lue depuis le trunk, "whoever wrote it" (quel qu'en soit l'auteur). - Une vue dans l'application. La documentation décrit l'outil et sa réponse, pas une page du navigateur qui affiche le rapport.
- Le Markdown n'est "not parsed yet" (pas encore analysé) ; une page ne peut donc pas être elle-même le côté gouverné.