◆ VENABILI

Sous le capotUnder the hood

La mécanique, pour ceux qui jugent sur la mécanique. The mechanics, for those who judge by the mechanics.

Venabili n'est pas un framework de code. C'est du markdown, du YAML et quelques scripts posés sur les runtimes du marché — et une machinerie de déterminisme autour, pour que rien de ce qui est déclaré ne soit faux. Voici la carte, en six schémas, puis ce qui bloque — et ce qui est vérifié, mécaniquement. Venabili is not a code framework. It is markdown, YAML and a few scripts laid on top of the market's runtimes — with determinism machinery around them, so that nothing declared can be false. Here is the map, in six diagrams, then what blocks — and what is verified, mechanically.

Provenance. Tout ce qui suit est tiré du dépôt et de sa documentation d'architecture — elle-même générée depuis le dépôt et vérifiée par doctor à chaque push et à l'horaire : si elle dérive, doctor rougit. Provenance. Everything below is drawn from the repository and its architecture documentation — itself generated from the repository and verified by doctor at every push and on schedule: if it drifts, doctor goes red.

Premier tempsFirst movement

Six schémas.Six diagrams.

Même grammaire partout : en sarcelle, ce qui vient du Core ; en violet, ce qui est à vous ; en rouille, les points où une clé ou un humain tranche. Plein : distribution et flux ; tirets : l'apprentissage qui remonte. Aucun trait n'est un lien de confiance. One grammar throughout: teal for what comes from the Core; violet for what is yours; rust for the points where a key or a human decides. Solid: distribution and flows; dashed: learning on its way up. No line is a trust relationship.

1

Quatre étages, une topologie.Four levels, one topology.

Le motif éprouvé source → satellite, généralisé d'un étage. Le Core est l'unique amont — anglais, semver, publiable. Chaque Node est l'instance d'une entreprise : il vendorise le Core à une version épinglée et y ajoute sa couche de domaine. Aucune copie ne vit en parallèle : chaque swarm en production consomme le Core. Les flux montants — leçons, backlog — passent toujours par des canaux dédiés, jamais par des commits croisés : chaque dépôt n'a qu'un seul rédacteur. The proven source → satellite pattern, generalized one storey up. The Core is the single upstream — English, semver, publishable. Each Node is one business's instance: it vendors the Core at a pinned version and adds its own domain layer. No copy lives alongside it: every swarm in production consumes the Core. Upstream flows — lessons, backlog — always travel dedicated channels, never cross-commits: every repository stays single-writer.

Venabili Core venabili.ca · EN · publiable · CORE_VERSION venabili.ca · EN · publishable · CORE_VERSION l'unique amont — un seul rédacteur the single upstream — single-writer Node — entreprise A Node — company A Core vendorisé · version épinglée Core vendored · pinned version + sa couche de domaine, dans son dépôt + its domain layer, in its own repo Node — entreprise B Node — company B bootstrappé du Core bootstrapped from the Core sans une ligne de l'entreprise A without one line from company A postes · credentials par rôle workstations · role-scoped credentials postes · tirage en sens unique workstations · one-way pull vendorisé ↓ vendored ↓ leçons ↑ lessons ↑ bootstrap ↓ bootstrap ↓ leçons ↑ lessons ↑ gouvernance, distribution ↓ governance, distribution ↓ apprentissage ↑ — canal dédié learning ↑ — dedicated channel

Core · Nodes · Agents · Network — le Network est la somme de tous ces flux.Core · Nodes · Agents · Network — the Network is the sum of all these flows.

2

Une source, deux runtimes.One source, two runtimes.

Les fiches d'agents (*.agent.md) et les blocs du Core sont du markdown et du YAML lisibles par n'importe quel runtime — aucun invariant ne vit uniquement dans un mécanisme propriétaire. compose remplit les slots et résout les tiers de modèles vers des identifiants épinglés. L'adaptateur claude-code compile un plugin par Node ; l'adaptateur anthropic-runtime est la boucle d'API portable : un futur fournisseur est l'extension d'un seul module, pas une refonte. Chaque mécanisme couplé a son jumeau descriptif — et un check le prouve. Agent cards (*.agent.md) and the Core blocks are markdown and YAML any runtime can read — no invariant lives only inside a proprietary mechanism. compose fills the slots and resolves model tiers to pinned identifiers. The claude-code adapter compiles one plugin per Node; the anthropic-runtime adapter is the portable API loop: a future provider is an extension of one module, not a rewrite. Every coupled mechanism has a descriptive twin — and a check proves it.

.agent.md + blocs du Core + Core blocks markdown · yaml compose slots · tiers tiers → alias → id épinglé tier → alias → pinned id adapters/claude-code build.py · sync.py plugin Claude Code · Cowork anthropic-runtime boucle portable · ADR-001 portable loop · ADR-001 API invoke.py — un module invoke.py — one module check twins twins check même roster des deux côtés same roster on both sides jumeau descriptif · check wiring descriptive twin · wiring check workflow.json ⟷ settings.json

Axe 3 — la portabilité est une contrainte de design dès la v1 ; le multi-fournisseur viendra après la discipline d'évals cross-modèle, jamais avant.Axis 3 — portability is a design constraint from v1; multi-provider comes after the cross-model evals discipline, never before.

3

L'anatomie d'un Node — ce qui est à vous, ce qui est au Core.Anatomy of a Node — what is yours, what is the Core's.

Six couches, dont le lieu de vie est fixé par construction. Les trois premières viennent du Core, vendorisées en lecture seule à une version épinglée. Les deux suivantes sont à vous : votre domaine, vos liaisons capacité → outil, votre politique d'accès — dans votre propre dépôt. La dernière ne va jamais dans git : secrets, credentials par rôle, connecteurs — par poste. Le Core ne nomme jamais un outil concret ; le Node lie les capacités abstraites aux siens. Six layers, each with a home fixed by construction. The first three come from the Core, vendored read-only at a pinned version. The next two are yours: your domain, your capability → tool bindings, your access policy — in your own repository. The last one never enters git: secrets, role-scoped credentials, connectors — per workstation. The Core never names a concrete tool; the Node binds abstract capabilities to its own.

vendorisé du Core vendored from the Core lecture seule · version épinglée read-only · pinned version à vous yours dans votre dépôt in your repository jamais dans git never in git par poste per workstation 1 · CORE invariants · skills méta · hooks · mémoire · tooling invariants · meta-skills · hooks · memory · tooling 2 · PACKS les rôles génériques que le Node adopte the generic roles the Node adopts 3 · OVERLAY RÉGIONAL 3 · REGIONAL OVERLAY matière locale réutilisable — ex. qc-ca : Loi 25, TPS/TVQ reusable local matter — e.g. qc-ca: Law 25, GST/QST 4 · DOMAINE 4 · DOMAIN vos agents, vos skills, vos outils, votre marque your agents, your skills, your tools, your brand 5 · LIAISONS & POLITIQUE 5 · BINDINGS & POLICY instance.yaml — identité, langue, capacité → outil, RBAC instance.yaml — identity, language, capability → tool, RBAC 6 · PAR POSTE 6 · PER WORKSTATION secrets · credentials à portée de rôle · connecteurs MCP secrets · role-scoped credentials · MCP connectors VIT LIVES vendorisé, épinglévendored, pinned vendorisévendored vendorisévendored le dépôt du Nodethe Node's repo le dépôt du Nodethe Node's repo le poste seulementthe workstation only Une capacité s'appelle « kb.search » ou « crm.person.create » — jamais par le nom d'un outil. Le Node dit lequel. A capability is called "kb.search" or "crm.person.create" — never by a tool's name. The Node says which.

Possession réelle — le Node est votre dépôt ; le Core y est vendorisé, épinglé, remplaçable. Rien de ce qui vous appartient ne dépend d'un poste.Real ownership — the Node is your repository; the Core sits in it vendored, pinned, replaceable. Nothing you own depends on a workstation.

4

La chaîne de garde-fous — des verrous, pas des habitudes.The guardrail chain — locks, not habits.

Le déterminisme est imposé par la machinerie. Au commit, un changement du Core sans son entrée de journal et son CHANGELOG est bloqué ; un message de commit sans le pourquoi, refusé. Au push, une chaîne qui ressemble à un secret bloque ; doctor rend son verdict. À la release, sanitisation, version, puis arrêt pour revue humaine. À l'exécution, les hooks encadrent chaque session, là où le runtime les émet — dont memory_write, qui juge le fichier de mémoire tel qu'il serait après l'écriture : sans étiquette, hors plafond, avec un secret ou un renseignement personnel non déclaré, il n'est pas écrit — et la seule frontière dure est la clé : une politique d'accès appliquée par des credentials à portée de rôle, que ni la prose ni le modèle ne peuvent outrepasser. Chaque garde-fou est censé battre ; s'il cesse, doctor le dit — le silence n'est jamais un feu vert. Determinism is enforced by machinery. At commit, a Core change without its journal entry and CHANGELOG is blocked; a commit message without the why, refused. At push, a secret-shaped string blocks; doctor gives its verdict. At release, sanitization, version, then a stop for human review. At runtime, hooks frame every session, wherever the runtime emits them — memory_write among them, which judges the memory file as it would be after the write: unlabeled, over its ceiling, carrying a credential or undeclared personal information, it is not written — and the only hard boundary is the key: an access policy enforced by role-scoped credentials that neither prose nor the model can overstep. Every guardrail is meant to beat; if it stops, doctor says so — silence is never a green light.

AU DÉPÔT — chaque commit, chaque push, chaque release IN THE REPOSITORY — every commit, every push, every release commit pre-commit currency de doc — bloque doc currency — blocks commit-msg le pourquoi, ou refus the why, or refusal historique local local history pre-push scan de secrets — bloque · doctor — avise secret scan — blocks · doctor — advises remote release.py sanitisation → version → arrêt pour revue humaine sanitization → version → stop for human review local — ne pousse ni ne tague jamais local — never pushes, never tags À L'EXÉCUTION — chaque session AT RUNTIME — every session session session_start user_prompt pre_tool_use memory_write delegation stop hooks — annoncer, confirmer, journaliser, borner hooks — announce, confirm, log, limit la clé the key la seule frontière dure the only hard boundary credentials à portée de rôle role-scoped credentials battements → liveness → doctor heartbeats → liveness → doctor absent = on ne sait pas — jamais « propre » ; un garde-fou muet crie absent = we don't know — never "clean"; a mute guardrail shouts

La règle — une frontière n'est réelle que là où elle est mécanique ; la prose et les hooks consultatifs ne sont jamais une frontière de sécurité, seule la clé l'est.The rule — a boundary is only real where it is mechanical; prose and advisory hooks are never a security frontier, only the key is.

5

La boucle anti-dérive — la dérive se prouve, elle ne se présume pas.The anti-drift loop — drift is proven, never presumed.

Aucun Node ne s'écarte du Core en silence. Une leçon vérifiée dans un Node remonte par la moisson — la porte 4 d'un chantier — et atterrit dans une file unique avec sa décision : réconcilier, différer, assumer. Réconciliée, elle devient une nouvelle version du Core. Chaque Node la vendorise à son rythme (git archive, version épinglée), puis dist-diff compile le plugin avant et après : équivalent, ou le diff est lu et accepté. doctor tient la porte au push. Pendant l'extraction, une carte d'empreintes mesurait la dérive d'une copie qui vivait à côté du Core ; cette coexistence a pris fin : il ne reste plus de copie à surveiller, seulement des versions à prouver. No Node drifts from the Core in silence. A lesson verified in a Node rises through the harvest — a worksite's gate 4 — and lands in a single queue with its decision: reconcile, defer, accept. Once reconciled, it becomes a new Core version. Each Node vendors it at its own pace (git archive, pinned version), then dist-diff compiles the plugin before and after: equivalent, or the diff is read and accepted. doctor holds the gate at push. During extraction, a fingerprint map measured the drift of a copy living alongside the Core; that coexistence is over: there is no copy left to watch, only versions to prove.

Node une leçon vérifiée a verified lesson Moisson Harvest porte 4 d'un chantier a worksite's gate 4 backlog.md un verdict par delta one verdict per delta réconcilier reconcile la règle monte au Core the rule rises into the Core différer defer reste signalée dans la file stays flagged in the queue assumer accept la divergence est écrite the divergence is recorded réconcilier ↓ reconcile ↓ Core nouvelle CORE_VERSION · semver new CORE_VERSION · semver sync-core git archive · version épinglée git archive · pinned version dist-diff plugin avant ↔ après plugin before ↔ after équivalent — ou diff lu et accepté equivalent — or diff read and accepted doctor · porte au push doctor · gate at push Aucune version n'atteint un poste sans avoir été prouvée — jamais sur la confiance. No version reaches a seat without being proven — never on trust.

Leçon ≠ instance — ce qui monte au Core est la règle transférable ; l'histoire et le confidentiel restent dans le Node.Lesson ≠ instance — what rises to the Core is the transferable rule; the story and the confidential stay in the Node.

6

La fédération — la gouvernance descend, l'apprentissage monte.Federation — governance flows down, learning flows up.

Le Network est bidirectionnel et fédératif. Vers le bas : politique, garde-fous, versions épinglées — la dérive par poste devient impossible, pas improbable. Vers le haut : la leçon d'un agent, une fois vérifiée, devient la mémoire de toute l'organisation — la leçon transférable séparée de l'instance confidentielle, qui reste dans le Node — mécaniquement : chaque mémoire porte sa classe, sa nature et sa portée, et un renseignement personnel ne dépasse jamais le Node. Une seule intelligence qui cumule et se gouverne ; sa mémoire fédérée — le cerveau commun — est la surface naturelle du service géré. La descente est mécanique dès aujourd'hui (version épinglée, tirage en sens unique) ; la mémoire fédérée opérée et curée, elle, est la Phase 4. The Network is bidirectional and federative. Downward: policy, guardrails, pinned versions — per-workstation drift becomes impossible, not merely unlikely. Upward: one agent's lesson, once verified, becomes the whole organization's memory — the transferable lesson separated from the confidential instance, which stays in the Node — mechanically: every memory carries its class, its kind and its reach, and personal information never rises above the Node. One intelligence that compounds and governs itself; its federated memory — the common brain — is the managed service's natural surface. The downward path is mechanical today (pinned version, one-way pull); the operated, curated federated memory is Phase 4.

Cerveau commun Common brain Core + mémoire fédérée Core + federated memory curée, vérifiée, à vous curated, verified, yours gouvernance ↓ governance ↓ politique · garde-fous · versions épinglées policy · guardrails · pinned versions la dérive par poste devient impossible per-workstation drift becomes impossible apprentissage ↑ learning ↑ la leçon vérifiée d'un agent one agent's verified lesson devient la mémoire de tous becomes everyone's memory l'instance reste locale the instance stays local cerveau commun opéré · phase 4 operated common brain · phase 4 Une seule intelligence qui cumule et se gouverne — pas quarante assistants qui dérivent. One intelligence that compounds and governs itself — not forty drifting assistants.

Le moat — ce que les plateformes livrent par siège, la fédération le livre à l'échelle de l'entreprise, sous gouvernance.The moat — what platforms deliver per seat, federation delivers at the scale of the company, under governance.

Second tempsSecond movement

Ce qui bloque, et ce qui est vérifié.What blocks, and what is verified.

Pour la diligence : ce qu'un acquéreur, un investisseur ou un CTO peut exiger de voir tourner — pas de lire. doctor répond à une seule question : est-ce que ça compile et tourne vraiment, et tout ce qui est déclaré est-il réel ? For diligence: what an acquirer, an investor or a CTO can demand to see run — not read. doctor answers one question: would this actually compile and run, and is everything declared real?

TransférableTransferable

La mécanique se lit sans le fondateur.The mechanics read without the founder.

Runbooks rejouables, journaux de chantier committés, incidents devenus verrous, documentation d'architecture générée depuis le dépôt. Le risque homme-clé est traité par des artefacts, pas par des promesses.Replayable runbooks, committed worksite journals, incidents turned into gates, architecture documentation generated from the repository. Key-person risk is addressed with artifacts, not promises.

PossédéOwned

Le Node est votre dépôt.The Node is your repository.

Le Core y est vendorisé à une version épinglée, en lecture seule, remplaçable ; vos données et votre domaine ne quittent pas votre dépôt. Le service géré se pose par-dessus une couche exportable — il l'opère et la cure, sans jamais la retenir.The Core sits in it vendored at a pinned version, read-only, replaceable; your data and your domain never leave your repository. The managed service sits on top of an exportable layer — it operates and curates it, never holds it.

ÉprouvéProven

Extrait de la production, et la production y est revenue.Extracted from production — and production moved onto it.

Le noyau est extrait de sept mois de production, pas réécrit de zéro — ce qui y naît en amont est marqué comme tel. L'extraction a été auditée artefact par artefact ; une seconde swarm, bootstrappée du Core en moins d'une heure, a prouvé le noyau réutilisable ; puis la swarm d'origine a migré sur le Core, lot par lot, chaque lot prouvé par dist-diff.The kernel is extracted from seven months of production, not rewritten from scratch — what is born upstream is marked as such. The extraction was audited artifact by artifact; a second swarm, bootstrapped from the Core in under an hour, proved the kernel reusable; then the original swarm itself migrated onto the Core, batch by batch, each batch proven by dist-diff.

doctor · 25 vérifications25 checks

Ce que doctor vérifie.What doctor verifies.

parsechaque fiche d'agent se lit — front-matter et corps validesevery agent card parses — valid front-matter and body
slotschaque slot référencé est définievery referenced slot is defined
handoffschaque passage de relais pointe vers un agent réelevery handoff points at a real agent
bindingschaque capacité déclarée a une liaison vivanteevery declared capability has a live binding
twinsles deux runtimes voient le même rosterboth runtimes see the same roster
modelschaque tier de modèle résout vers un alias et un id épinglésevery model tier resolves to a pinned alias and id
accessla politique RBAC est cohérente — aucun principal au-dessus de son rôlethe RBAC policy is coherent — no principal above its role
hooksle verrou de commit est installé — core.hooksPath pointe sur les hooks du dépôtthe commit gate is installed — core.hooksPath points at the repository's hooks
livenesschaque garde-fou a battu récemment — le silence se lit « on ne sait pas »each guardrail has beaten recently — silence reads "we don't know"
versionCORE_VERSION est un semver valide et le plugin bâti y correspondCORE_VERSION is valid semver and the built plugin matches it
wiringintention (workflow.json) et câblage (settings.json) déclarent les mêmes événementsintent (workflow.json) and wiring (settings.json) declare the same events
changelogchaque puce du CHANGELOG tient sa propre ligneevery CHANGELOG bullet holds its own line
docsles docs générés correspondent à une régénération fraîche et couvrent chaque composantgenerated docs match a fresh regeneration and cover every component
testsla suite de tests tourne et passe — doctor n'est jamais vert sans l'avoir vue passerthe test suite runs and passes — doctor is never green without having seen it pass
classificationchaque fichier de mémoire est un compartiment étiqueté dans ses plafonds — ni secret, ni renseignement personnel non déclaré ; la mémoire du Core est publiqueevery memory file is a labeled compartment within its ceilings — no credential, no undeclared personal information; Core memory is public
telemetryopt-in par Node ; si activée : point de terminaison https réel, jeton hors du dépôt, envoi récent — un Node silencieux est inconnu, jamais sain ; ce qui part : des états et des étiquettes, jamais une ligne de mémoireopt-in per Node; when on: a real https endpoint, the token outside the repository, a recent send — a silent Node is unknown, never healthy; what leaves: states and labels, never a memory line
schemachaque clé d'instance.yaml est lue par le Core — une clé mal tapée est nommée, pas ignoréeevery instance.yaml key is one the Core reads — a mistyped key is named, not ignored
runtime_slotsle préambule et les instructions du runtime portable se composent sans slot orphelinthe portable runtime's preamble and instructions compose with no orphan slot
node_hooksles hooks propres au Node sont déclarés et exécutablesthe Node's own hooks are declared and runnable
node_checksles vérifications propres au Node sont déclarées, exécutables — et elles passentthe Node's own checks are declared, runnable — and they pass
plugin_closurechaque plugin de siège est fermé : aucun agent n'y délègue hors de son pluginevery seat plugin is closed: no agent delegates outside its plugin
marketplacela version publiée est celle du Node, et le jeton de publication n'expire pas bientôtthe published version is the Node's, and the publish token is not about to expire
invariant_refschaque renvoi « §N » pointe sur la règle qu'il prétend citerevery « §N » reference points at the rule it claims
usageopt-in ; si activée : un point de terminaison https réel, une clé par plugin hors du dépôt, le jour du Node (fuseau déclaré)opt-in; when on: a real https endpoint, one key per plugin outside the repository, the Node's day (declared zone)
tool_metricsopt-in ; si activée : compteurs par outil MCP — jamais un argument ni un résultat —, une clé vnbm_ par Node hors du dépôt ; un siège nommé dans les compteurs exige l'avis Loi 25opt-in; when on: counters per MCP tool — never an argument nor a result —, one vnbm_ key per Node outside the repository; a seat named in the counters requires the Loi 25 notice

Les verrousThe locks

Ce qui bloque — et ce qui avise.What blocks — and what advises.

pre-commitCurrency de doc — un changement du Core sans son CHANGELOG et son journal de chantier ne passe pas le commit.Doc currency — a Core change without its CHANGELOG and worksite journal cannot be committed.
commit-msgLe pourquoi, ou rien — le message boilerplate est refusé ; l'audit ne doit jamais être aveugle.The why, or nothing — boilerplate messages are refused; the audit must never go blind.
pre-pushScan de secrets — une chaîne qui ressemble à une clé bloque le push ; un secret dans l'historique est éternel.Secret scan — a key-shaped string blocks the push; a secret in history is forever.
releaseSanitisation, version, revue — le Core naît publiable : zéro secret, zéro nom de client ; puis un humain tranche.Sanitization, version, review — the Core is born publishable: zero secrets, zero client names; then a human decides.
doctorAvise, ne bloque pas — la carte d'architecture et le README sont des fonctions pures du dépôt ; s'ils dérivent, doctor rougit au push et à l'horaire. Un avis, par doctrine : un contrôle qui bloque sur la santé se contourne à la première urgence.Advises, never blocks — the architecture map and the README are pure functions of the repository; if they drift, doctor goes red at push and on schedule. Advisory by doctrine: a control that blocks on health gets bypassed at the first urgency.
memory-writeCe qui se sait est gouverné comme ce qui se fait — une mémoire sans étiquette, un secret, un renseignement personnel non déclaré ne s'écrivent pas ; ce qu'un rôle lit dépend de sa clearance et de celle de la personne qu'il sert ; ce qu'un poste tient dépend de son rôle.What is known is governed like what is done — an unlabeled memory, a credential, undeclared personal information are not written; what a role reads depends on its clearance and on the clearance of the person it serves; what a seat holds depends on its role.
la cléRBAC appliqué par les credentials — ce qui n'est pas dans la clé est impossible, quoi que fasse le modèle.RBAC enforced by credentials — what isn't in the key is impossible, whatever the model does.

État du chantier. Noyau v0.2 extrait et audité · deux runtimes sur une source · 16 vérifications · documentation générée. Les contrats de capacités et les packs de rôles se remplissent au premier Node externe — rien n'entre en stock « au cas où ». La mémoire fédérée opérée — le cerveau commun — est la Phase 4. Le multi-fournisseur suit la discipline d'évals cross-modèle, pas l'inverse. Where the build stands. Kernel v0.2 extracted and audited · two runtimes on one source · 16 checks · generated documentation. Capability contracts and role packs are filled by the first external Node — nothing is stocked "just in case". The operated federated memory — the common brain — is Phase 4. Multi-provider follows the cross-model evals discipline, not the other way round.

En un motIn a word

Une habitude se saute sous pression ; un verrou, non. Ce qui bloque ici bloque mécaniquement — et ce qui avise ne se tait jamais. A habit is skipped under pressure; a lock is not. What blocks here blocks mechanically — and what advises never goes quiet.

Vérifiable, pas seulement lisible.Verifiable, not merely readable.

La visionThe vision Le manifesteThe manifesto Voir la mécanique tournerSee the mechanics run