Contrats et validation métier

Le contrat entre analyse et application

Le texte libre convient à une explication humaine ; l’application a besoin de champs qu’elle peut vérifier. BacklogDraft transporte Title, Kind, Priority, Component, Summary et ClarifyingQuestions. Le schéma demandé via ChatResponseFormat.ForJsonSchema<BacklogDraft>() guide la génération. Le programme désérialise ensuite response.Text avec System.Text.Json et traite JsonException et objet null avant toute action.

On évite ainsi de chercher le mot « high » dans une phrase pour décider d’une insertion. La structure rend les erreurs contrôlables, mais ne garantit pas que la conclusion du modèle soit juste. Les anciennes signatures RunAsync<T> ne sont pas la procédure de ces programmes.

Valider les domaines et les bornes

public string[] Validate(bool forAction = true)
{
    var errors = new List<string>();
    if (!Text(Title, 120)) errors.Add("Title must contain 1 to 120 characters.");
    if (!Text(Summary, 2000)) errors.Add("Summary must contain 1 to 2000 characters.");
    if (Kind is not ("Bug" or "Feature" or "Question")) errors.Add("Unknown kind.");
    if (Priority is not ("low" or "medium" or "high")) errors.Add("Unknown priority.");
    if (!Catalog.Names.Contains(Component)) errors.Add("Unknown component.");
    if (ClarifyingQuestions is null || ClarifyingQuestions.Length > 2
        || ClarifyingQuestions.Any(q => !Text(q, 300))) errors.Add("Invalid clarification questions.");
    if (forAction && ClarifyingQuestions is { Length: > 0 }) errors.Add("Clarification is required before writing.");
    return errors.ToArray();

shared/Maf.Backlog/Contracts.cs · L8–L19 · 9a895c94534c

Code source · Maf.Backlog · Dossier

• shared/Maf.Backlog/Maf.Backlog.csproj

urgent et SecretAdmin peuvent être des chaînes JSON parfaitement valides et restent interdits. Le host refuse au lieu de remplacer silencieusement urgent par high ou d’ajouter un composant. Catalog.Names est l’allowlist de confiance ; un document fourni par un utilisateur ne peut pas l’étendre.

Une analyse utile peut bloquer l’action

Une demande telle que « Ça ralentit parfois » ne fournit pas forcément de composant ni de reproduction. Demander une ou deux précisions est un résultat utile. Validate(forAction: false) vérifie la forme des questions ; Validate() refuse l’écriture tant que le tableau contient une question. Le tableau vide signifie qu’aucune clarification n’est déclarée ; cela ne certifie pas que le modèle a compris tous les faits.

Dans Demo050, les questions et erreurs sont affichées ; l’utilisateur soumet ensuite une nouvelle demande précisée. Il n’existe pas de boucle de clarification persistante qui fusionnerait automatiquement les tours. Ne pas corriger le draft après sa revue pour lui ajouter discrètement des informations.

Valide ne veut pas dire autorisé

Demo050 peut annoncer Valid actionable draft tout en n’exposant aucun outil d’écriture. L’admissibilité métier est une condition préalable. Le droit du host, l’approbation de cette proposition et son état non consommé restent à vérifier. Même une proposition admise peut contenir une conclusion métier fausse ; la revue humaine porte sur le contenu exact présenté.

Le contre-exemple historique d’EP001 utilisait un remboursement : un seuil de 100 autorisait une proposition automatique, 100–500 imposait une escalade et au-delà de 500 une revue manuelle. Une réponse JSON « approuvé » pour 1 250 pouvait respecter la forme tout en violant la règle. L’intérêt est de coder et tester cette contrainte indépendamment du prompt. Ces montants illustrent une politique fictive ; Demo100 utilise désormais urgent et SecretAdmin dans le backlog et n’exécute aucun remboursement.

var errors = draft.Validate();
Console.WriteLine(JsonSerializer.Serialize(draft));
if (errors.Length != 0) { Console.WriteLine(string.Join(" ", errors)); continue; }
Console.WriteLine("Valid actionable draft; no write tool is exposed.");

demos/Demo050_StructuredBusinessContract/Program.cs · L35–L38 · 9a895c94534c

Code source · Demo050 · Dossier

• demos/Demo050_StructuredBusinessContract/Demo050.App.csproj

• Demo100 — Controlled Action

Contre-exemples à rejouer

Comparer une demande claire de bug Auth, une demande ambiguë, une priorité urgent, un composant absent et un tableau de questions null. Les tests déterministes construisent directement ces objets : ils prouvent le refus de l’application même si un modèle réel ne génère pas le contre-exemple ce jour-là. Le test ne transforme pas le modèle par défaut en modèle qualifié.

Manipuler puis relier aux outils

• Demo050 — Structured Business Contract

• Analyse et action : Start/End

• Catalogue et preuve des outils