Documentație / Calitate și guvernanță

Contractul de calitate

Regulile de calitate stau într-un fișier versionat din depozit, nu în prompt, și se aplică la fel oamenilor și agenților.

Contractul de calitate este fișierul .ai/contract.json al proiectului tău. Definește câtă rigoare cere echipa: praguri de măsurare, acoperire, complexitate, dimensiunea modificărilor, căi protejate și excepții.

Îl aplică gate-ul motorului, hook-urile Git, CI-ul și agenții. Rezultatul nu depinde de cine scrie codul: o persoană, Yuli, Claude Code, Codex, Kiro sau Antigravity.

Dacă fișierul nu există sau nu este valid, Yuli folosește valorile implicite (criticitate Business). Fiecare câmp este opțional, așa că și un contract parțial funcționează.

Unde se editează

Deschide Centrul de guvernanță (șina din dreapta → Mai multe unelte sau paleta de comenzi cu Deschide Centrul de guvernanță) și intră în fila Contract.

Când salvezi cu Salvează și semnează, Yuli înregistrează modificarea cu git config user.name-ul tău. Poți vedea toate modificările în Istoricul contractului.

Criticitate

Criticitatea alege un profil complet de praguri. Există patru niveluri:

Valoare în fișier Etichetă în Yuli Când o folosești
low Scăzută Prototipuri, unelte interne, experimente.
business Business Aplicații de business. Este valoarea implicită.
regulated Reglementată Sisteme supuse auditului sau reglementării.
safety Critică pentru siguranță Software în care o defecțiune are consecințe grave.

Profiluri

Prag Scăzută Business Reglementată Critică pentru siguranță
Scor de acceptare 80 90 92 95
Runde de măsurare 2 3 4 5
Acoperire minimă 50 % 70 % 80 % 90 %
Complexitate cognitivă max. 20 15 15 10
Complexitate ciclomatică max. 15 10 10 8
Mutație minimă 0 % 0 % 60 % 75 %
Fișiere pe modificare 60 40 25 15
Linii pe modificare 2000 1000 600 400
Revizuire independentă Nu Nu Da Da
Blochează trișarea testelor Nu Da Da Da
Aplicare strictă Nu Nu Da Da

Poți înlocui un anumit prag în gates. Se schimbă doar acel câmp; restul continuă să provină din profil. Blochează trișarea testelor și Aplicare strictă depind doar de criticitate și nu pot fi înlocuite.

Scorul de acceptare și rundele din contract înlocuiesc setările locale ale fazei de Măsurare.

Structura fișierului

{
  "schemaVersion": 1,
  "criticality": "business",
  "gates": { "minCoverage": 75, "maxCyclomatic": null },
  "changeLimits": { "maxFiles": 40, "maxLines": 1000 },
  "protectedPaths": ["db/migrations/**"],
  "waivers": []
}
Câmp Ce definește
criticality low, business, regulated sau safety.
gates acceptanceScore, maxMeasureRounds, minCoverage, maxCognitive, maxCyclomatic, requireIndependentReview, minMutationScore. null preia valoarea din profil.
changeLimits maxFiles și maxLines pe modificare.
protectedPaths Globuri suplimentare, care se adaugă celor protejate implicit.
waivers Excepții cu dată de expirare.
architecture Straturi (layers cu name, paths, mayDependOn) și forbidCycles.
slos Obiective de serviciu: latencyP95Ms, availability sau errorRate.
licensePolicy Licențe permise (allow) și interzise (deny), prin SPDX sau pe familie, de exemplu strong-copyleft.
reviewer Revizor independent: requireOtherFamily, provider, model.
dataClassification Tipare de date cu nivelul lor: public, internal, confidential sau restricted.
finops Buget lunar pe serviciu și responsabilul acestuia.

Limitele modificărilor

Dimensiunea unei modificări se măsoară cu git diff --numstat. Fișierele de blocare (package-lock.json, yarn.lock, Cargo.lock, go.sum și altele similare) contează ca fișiere, dar liniile lor nu.

Depășirea limitei blochează cu aplicare strictă (Reglementată și Critică pentru siguranță). În celelalte profiluri este un avertisment.

Căi protejate

Un agent nu poate edita aceste fișiere, chiar dacă i se cere:

  • .ai/contract.json, .ai/quality.json și .ai/state/**
  • .claude/settings.json și .claude/settings.local.json
  • .githooks/**
  • .github/workflows/**, .gitlab-ci.yml și Jenkinsfile
  • CODEOWNERS și .github/CODEOWNERS

Comparația ignoră majusculele. Adaugă propriile căi în protectedPaths. O modificare a contractului salvată din Yuli rămâne în audit și contează ca aprobată.

Excepții (waivers)

O excepție permite ocolirea temporară și justificată a unei reguli.

Câmp Conținut
id Identificatorul excepției.
rule Regula exceptată: secrets, protectedPaths, testIntegrity, un anumit tip de trișare sau *.
path Globul la care se aplică. Gol înseamnă orice cale.
reason Motivul.
approvedBy Cine a aprobat-o.
expires Data de expirare, AAAA-MM-DD.
ticket Referință opțională.

O excepție este valabilă până în ziua din expires, inclusiv. O dată lipsă sau scrisă greșit contează ca expirată. La expirare, regula se aplică din nou, iar gate-ul semnalează acest lucru.

În interfață, fiecare excepție își afișează starea: În vigoare, Expiră curând, Expirată sau Dată invalidă.

testIntegrity exceptează simultan toate detectările de trișare în teste. Folosește-o cu o cale restrânsă și o dată apropiată.

Audit

Fiecare salvare adaugă o linie în .ai/state/contract-audit.jsonl cu data, autorul, hash-ul SHA-256 și un rezumat (de exemplu, „criticality business→regulated; waivers +1”).

Autorul este întotdeauna o persoană: numele indicat sau git config user.name-ul tău. „Yuli” și „Yuli Code” sunt respinși ca autori.

Pasul următor