Modules et packs

arka-deck combine trois familles qu’il ne faut pas confondre :

un module système fournit une capacité native de l’application ;
un addon ajoute une capacité first-party activable ou administrable ;
un pack apporte un contenu versionné appliqué à un projet : règles, profils, documents, flowmap, cards, prompts et event policies.

Cette page sert de carte produit pour comprendre ce qui est installé, ce qui est activé par projet, et ce qui devient source de vérité runtime.

Vue d’ensemble

Élément	Nature	Rôle	Source de vérité runtime
Cortex Lite	Module runtime local / sidecar	Graphe local projet, contexte agent, MCP `arka_runtime`	SurrealDB local + artefacts matérialisés
ArkaDoc	Module documentaire	Documents de travail, tasks, décisions, CR, verdicts QA	Documents projet + index Cortex Lite
Documentation projet	Vue produit	Lecture des livrables ArkaDoc et navigation par index	Routes documentation + ArkaDoc
Mission Guardian	Addon first-party	Administration et application des packs de gouvernance	Pack actif matérialisé dans Cortex Lite
Deck Guardian Lite	Guidance pack	Cadre alpha build in public injecté aux agents	Réglage gouvernance projet + injection prompt
Deck Guardian	Pack de gouvernance first-party	Cadre de mission par défaut d’un projet arka-deck	Artefacts du pack dans Cortex Lite
Guardian Runtime Compiler	Addon technique	Compile les artefacts du pack actif en injection compacte	Pack actif + état runtime
Expert Panel	Addon de capacité	Infrastructure Packs Métier non exposée dans cette release	Aucun pack publié par défaut
Squad Leader	Addon first-party	Compose une squad et identifie le leader	État projet + profils
Squad Orchestration	Addon first-party	Lance le travail multi-agents audité	Tasks ArkaDoc + squad + gates
Memory Local	Addon first-party	Capture et consolide la mémoire utile	Mémoire projet + Cortex Lite
Event Lab	Surface Mission Guardian	Observe, inspecte et simule les events modules	Catalogues events + pack actif

Cortex Lite

Cortex Lite est le runtime local du projet. Il tourne comme sidecar HTTP et s’appuie sur SurrealDB pour matérialiser un graphe local.

Son rôle n’est pas de stocker des fichiers. Il relie les objets utiles au runtime :

projet ;
documents ArkaDoc ;
mémoire ;
profils et squads ;
règles, modes, flowmaps et packs de gouvernance ;
events modules ;
outils MCP exposés aux agents.

Les agents n’ont pas besoin de déduire l’état du projet en parcourant le filesystem. Ils résolvent un contexte structuré via les routes locales et le MCP arka_runtime.

Si Cortex Lite n’est pas disponible, les capacités runtime locales d’arka-deck sont indisponibles : Mission Guardian, orchestration, mémoire structurée, ArkaDoc matérialisé et injections projet ne doivent pas être simulés.

ArkaDoc

ArkaDoc est le module documentaire d’arka-deck. Il sert à sortir le travail agentique du chat et à le rendre pilotable.

Types de documents

Type	Usage
`brief`	Cadrage, contexte, objectif, contraintes, questions ouvertes
`spec`	Spécification fonctionnelle ou technique
`task`	Travail assignable à un agent ou worker
`cr`	Compte-rendu de production
`qa_verdict`	Verdict QA sur une tâche ou une mission
`decision`	Décision humaine ou système traçable

Statuts

Statut	Sens produit
`draft`	Brouillon, pas encore prêt à être consommé
`ready`	Prêt : peut être validé, dispatché ou utilisé selon son type
`submitted`	Soumis : livré par un agent ou worker, en attente de revue
`accepted`	Validé
`rejected`	À reprendre
`archived`	Retiré du flux actif

Pour une task, l’UI expose les actions humaines simples Draft, Ready et Abort. Abort archive la task : elle reste traçable mais n’est plus prise en compte pour le dispatch.

Identifiants

Le document ArkaDoc est l’identifiant runtime stable. Une task peut contenir un task_id métier dans son payload, mais les commandes de dispatch utilisent l’id du document ArkaDoc exposé comme dispatch_task_id.

Relations

Un ArkaDoc peut référencer un autre document, une mémoire, une mission, un run, une session ou une pièce jointe. Ces relations permettent à Cortex Lite de construire un graphe consultable sans relire tous les documents complets.

Documentation projet

La Documentation projet est la vue lisible des livrables ArkaDoc. Elle n’est pas une bibliothèque statique ni un mock : elle lit les documents réels du projet.

Chaque document peut être consulté par :

vue humaine ;
données brutes ;
tags et résumé ;
estimation de tokens ;
blocs ;
relations.

L’objectif est de permettre aux agents et aux humains de retrouver le bon livrable sans injecter tout l’historique du projet dans chaque tour.

Mission Guardian

Mission Guardian administre les packs de gouvernance et applique leurs décisions runtime.

Il porte :

l’administration UI des packs ;
l’activation ou désactivation d’un pack sur un projet ;
les cards UI génériques de validation ;
l’Event Lab ;
la lecture du pack actif depuis Cortex Lite ;
les gates runtime visibles par l’utilisateur et les agents.

Mission Guardian ne doit pas décider à la place du pack. Le pack actif décrit la gouvernance ; le runtime exécute, trace et refuse quand une règle n’est pas satisfaite.

Deck Guardian Lite

Deck Guardian Lite est le défaut alpha pour les projets build in public. C’est un guidance_pack, pas un guardian_pack runtime.

Il apporte :

une checklist courte de conduite injectée aux tours agent ;
un badge/statut UI explicite : Guidance only ;
des limites transparentes : pas de cards runtime, pas de modes exécutables, pas d’event policy et pas de tool gate.

Il ne doit jamais être matérialisé comme mission_guardian_active_pack et il ne remplace pas la voie runtime Mission Guardian. Lite limite les dérives agent par instruction et transparence ; il n’enforce pas la gouvernance au runtime.

Mission Guardian full reste beta/experimental tant que la surface diagnostic runtime et la validation pack/runtime ne sont pas terminées.

Deck Guardian

Deck Guardian est le pack de gouvernance first-party par défaut. Il cadre un projet arka-deck standard. Aucun Pack Métier spécialisé n’est publié dans cette release.

Statut au 2026-05-27 — draft_for_validation. Deck Guardian est structurellement cohérent et passe les checks runtime étendus de cohésion (validator + findOrphanPackTools + findUnsupportedPackRoleEntries tous au vert). En revanche, le pack n’est pas encore marqué validated parce que : (a) certaines actions de gouvernance vivent dans pending_capabilities en attente du lot CapabilityRegistry à venir ; (b) les commandes humaines passent par cards (pas via tool_policy.mode_tools) ; (c) mission_guardian.assess_impact (obligatoire selon DG-QA-IMPACT-MANDATORY) attend l’implémentation du CapabilityRegistry. Le passage à validated interviendra à l’issue du prochain lot de stabilisation.

Il contient notamment :

registre des modes ;
transitions autorisées ;
flowmap ;
règles complètes ;
mini-rules ;
règles par mode ;
event policy ;
tool policy ;
prompt layers ;
templates de cards UI ;
documents requis ;
preview d’injection ;
JSON source du pack.

Deck Guardian est installé au démarrage d’un projet gouverné, puis matérialisé dans Cortex Lite. Après matérialisation, Cortex Lite devient la source de vérité runtime. Le core ne doit pas embarquer une copie hardcodée du pack pour décider à sa place.

Un projet peut aussi fonctionner sans guardian pack, en mode libre. Dans ce cas, les agents ne reçoivent pas le cadre de modes, gates, cards et documents attendus.

Packs Métier et guardian packs dédiés

Les Packs Métier ne sont pas exposés dans cette release publique. Cette section décrit le contrat cible : un pack métier ne sera publié que lorsqu’il portera sa gouvernance dédiée validée end-to-end.

Un Pack Métier installe un environnement spécialisé sur un projet : squad fixe, profils, skills, méthodes, documents, workers et règles métier.

Un Pack Métier n’override pas Deck Guardian. Il apporte son propre guardian pack dédié.

Principe :

1 pack métier -> 1 gouvernance dédiée -> 1 projet ciblé

Exemples de trajectoire, non publiés dans la release actuelle :

Expert Panel pourra fournir un guardian pack dédié par pack publié.
Un pack client privé comme LeadRadar doit porter son propre guardian pack, par exemple leadradar-guardian.

Cette séparation évite de transformer Deck Guardian en pack universel gonflé par des règles métier contradictoires.

Expert Panel

Expert Panel est l’infrastructure de capacité prévue pour installer des Packs Métier. Dans cette release, son catalogue runtime est vide par défaut et l’UI ne propose pas l’activation de pack métier.

Quand un futur pack validé sera activé :

l’activation est scopée au projet ;
la squad complète du pack est installée ;
le leader du pack ouvre la session ;
les documents attendus et workflows deviennent disponibles ;
le guardian pack dédié est matérialisé dans Cortex Lite ;
les agents reçoivent les injections correspondant au rôle réel de leur session.

L’utilisateur ne choisit pas les profils un par un pendant l’activation : le pack définit l’équipe complète.

Event Lab

Event Lab sert à comprendre et tester les events avant qu’ils déclenchent une gouvernance réelle.

Un module produit ses events. Le bus les diffuse. Mission Guardian les reçoit et le pack actif décide quoi en faire via event_policy.bindings.

Event Lab permet de :

voir les catalogues d’events déclarés par les modules ;
lire le stream d’events projet ;
inspecter si un event matche le pack actif ;
valider les bindings du pack ;
créer des scénarios dry-run.

Un scénario dry-run ne change pas le mode, ne crée pas de card et ne publie pas dans le bus runtime.

Règle de lecture simple

Pour savoir où se trouve la responsabilité :

Question	Responsable
Où sont les documents ?	ArkaDoc
Où sont les relations runtime ?	Cortex Lite
Qui administre la gouvernance ?	Mission Guardian
Qui définit la gouvernance ?	Guardian pack actif
Qui compile l’injection agent ?	Guardian Runtime Compiler
Qui activera des packs métier validés ?	Expert Panel
Qui coordonne une squad ?	Squad Leader + Squad Orchestration