comun/docs/reguli_lucru.md

# Reguli de lucru agent (comune proiectelor ROA VFP)

1. Modificari de cod: diff ca FISIER `docs\diff_runda<N>_<subiect>.patch`
   (`git diff --no-index <baseline.bak> <editat>`), nu in terminal. **COMMIT-ul** e singurul pas
   care asteapta aprobarea patch-ului. Write-back-ul in binar (txt2vcx) si testele se fac IMEDIAT
   dupa editarea `.vc2`/`.sc2`, fara sa astepti raspunsul — inclusiv pe `COMUN` — ca sa ajungi la
   review cu rezultatele testelor, nu cu o propunere netestata; daca nu merge, revii cu
   `git checkout` pe binare (`.vcx`+`.vct`) sau cu write-back din `*.pre_runda*.bak`.
   Patch-urile (in .gitignore, `docs/diff_runda*.patch`) nu se comit niciodata, raman local.
   Curatenia de dinainte de commit NU se face pe cap de agent, ci cu
   `powershell -File COMUN\utile\curatenie.ps1` (`-DryRun` listeaza fara sa stearga): patch-uri,
   handoff-uri/planuri de runda, `*.pre_runda*.bak`, `.bak`-urile din cache-ul text si artefactele
   de test (`screenshots*`, `uisync*`, `.fxp`, `.err`, loguri). Sterge doar fisiere neurmarite de
   git — cele tracked sunt sarite.
2. Comentarii in cod SI in scripturile de migrare `.sql`: minime, strict functionale, descriu
   comportamentul CURENT (ca si cum ar fi scris asa de la inceput). **Doar daca e cazul** — un
   comentariu se scrie acolo unde explica o **ramura** sau un **filtru** care nu se citeste singur,
   ca sa se inteleaga codul; unde codul e limpede, nu se comenteaza. O linie de regula, 2-3 doar
   pentru metode cu contract nebanal (parametri, cursor asteptat/lasat deschis, pozitionare la
   iesire), 4-5 in antetul unui script de migrare (ce e obiectul si ce contract are). Istoricul
   modificarilor sta DOAR in ANTETUL fisierului (niciodata inline) — la fel in `.prg`, in `.sql`
   si in PL/SQL Oracle.
   INTERZIS in comentariu: nume de agent ("claude"), referinte la planuri, stories, propuneri,
   decizii, etape sau erori (`docs/plan_*.md`, `docs/propuneri_*.md`, "#6", "S4", "M2", "T3",
   "dec.6", "runda27", "E7", "D-H2"), trimiteri la rapoartele din `docs/` ("vezi raportul,
   sectiunea ..."), justificarea alegerii facute (de ce numele acesta, de ce s-a respins varianta
   cealalta), istoricul modificarii ("inlocuieste...", "nu mai depinde de...", "mutat din..."),
   date si autori pe cod nou.
   Comentarii vechi in stil jurnal nu se rescriu din oficiu — doar cand blocul e oricum atins
   sau la cerere explicita.
   Antet: o singura intrare CUMULATIVA per functionalitate (`*!* DD.MM.YYYY` / `*!* autor` /
   `*!* ce face, 1-2 fraze`) — la revenire se rescrie intrarea, nu se adauga alta; autorul e cine
   semneaza livrarea (ex. `marius.mutu`), niciodata agent. Doar comportamentul final — fara
   revizii/runde/patch-uri/corectii. La rezolvari de erori: fara comentarii.
   Explicatiile merg in docs/ sau in mesajul de commit, nu in cod.
   Changelog (`changelog_<aplicatie>.txt`): strictul necesar, pe limba utilizatorului, non-tehnic
   — 1-3 fraze/intrare, fara detalii de implementare, fara enumerarea locurilor atinse. Cat timp
   lucrarea n-a ajuns la utilizatori, erorile introduse si corectate in interior NU se mentioneaza
   — intrarea descrie functionalitatea finala, `:nou:`/`:modificare:`; `:eroare:` doar pentru erori
   care au fost in productie.
3. Modificari minime si SCOPED: doar ce s-a cerut, doar pe cazul cu problema, fara refactorizari
   din oficiu. Cauta intai ce exista (`inventar-comun.md`) si refoloseste; daca lipseste ceva,
   propune COMPLETAREA unei functii/tabele/view comune, nu o varianta paralela. 80/20: solutia cea
   mai simpla care rezolva cazul real. Completeaza `inventar-comun.md` la orice descoperire/creare
   de element comun nedocumentat.
   **Cod nou: clase in `.prg`, nu metode in `.vcx`/`.scx`.** Logica se incapsuleaza intr-o clasa
   (`Define Class ... As Custom`) dintr-un `.prg`; formularul sau clasa vizuala doar instantiaza
   obiectul (`Createobject`) si il apeleaza, metoda din binar ramanand un apel de o linie. Sablon:
   `COMUN\programe\anaf_efactura.prg` (`AnafeFacturaServer`, `ANAFeFactura`), apelat din
   `clase\anaf_efactura.vcx`. Motivul e de intretinere: un `.prg` se editeaza direct si diff-ul lui
   se citeste in git, pe cand codul pus ca metoda in binar trece prin FoxBin2Prg si write-back si
   se urmareste greu.
4. Testare headless (fara IDE): `vfp9.exe -A -T "<script.prg>" <param>` din PowerShell.
   Mediu, sabloane, capcane, depanare: `depanare_testare_vfp.md`.
5. Editare .vcx/.scx pe text (cache, cp1250 byte-safe, fidelity-check): `flux-editare-vfp-text.md`.
   Cautare in binare: `cautare_vcx_vct.md`. Versiunile `.??2` sunt instantanee, pot fi mai vechi
   decat binarul — verifica mtime inainte de concluzii; continutul real e in `.PJX`.
6. Delegare: implementarile, testele, verificarile si cercetarile se dau unor subagenti Sonnet in
   background (lane-uri paralele); sesiunea principala doar orchestreaza si verifica, ca sa nu i
   se umple contextul. Misiuni lungi: subagenti proaspeti per sarcina (max ~200-250k
   tokens/subagent), nu unul singur cu context acumulat; handoff compact pe disc:
   `orchestrare-subagenti.md`.
   **Verificarea a ce se intoarce** — pentru executie delegarea merge, pentru concluzii nu:
   - **citeste contractul functiei apelate, nu-l presupune.** Un raport care descrie corect
     structura codului poate gresi sensul: ex. `goExecutor.oExecute` intoarce succes/insucces
     (`CT_SUCCES`/`CT_INSUCCES`), NU numarul de randuri — o garda `If lnSucces > 0` citita ca
     "are randuri" a produs un bug inexistent, raportat ca blocant. Deschide functia.
   - **fix ingust, nu supra-constructie.** Cand premisa se corecteaza, corectia se restrange:
     mecanismele noi introduse "ca sa fie sigur" diverg de la codul-sablon si blocheaza
     refolosirea lui in alta parte.
   - **"zero cazuri in date" nu dovedeste nimic** pe scheme cu date de test; raspunsul vine din
     cod. Si invers: o potrivire de cifre pe 1-2 documente nu e o regula.
   - **cere raportul sa separe "testat" de "analizat static"**, si ce n-a putut fi acoperit. Un
     agent care nu e intrebat explicit va prezenta amandoua la fel.
   - **spune-i ca poate infirma briefingul.** Altfel implementeaza corectia ceruta chiar cand a
     descoperit ca nu e nevoie de ea.
7. Conventii obligatorii, de citit cand atingi zona respectiva:
   - editezi fisiere `.vc2`/`.sc2`, dar si `.prg` (ex. `programe\ocautare.prg`, unde `s`-urile cu
     virgula din `masina`/`si contul`/`transa` sunt octetul `0xBA`) -> `conventie_encoding_cp1252.md`.
     Antetul FoxBin2Prg declara `CPID="1252"`, dar octetii diacriticelor sunt de fapt **cp1250**
     (`0xE3`=a cu caciula, `0xFE`=t cu virgula, `0xAA`=S majuscul cu virgula, `0xBA`=s minuscul cu
     virgula) - nu trata eticheta din antet ca adevarul despre encoding. Orice write cu un tool ce
     nu pastreaza octetii nativ (Edit/Write) corupe caracterele >= 0x80 din TOT fisierul (`0xBA` ->
     `EF BF BD`), chiar la o singura linie schimbata, si o repeta la FIECARE scriere - **nu
     re-encoda niciodata fisierul: lucreaza pe octeti (`byte[]`) sau scrie strict ASCII in
     continutul nou**; editeaza tot ce ai de editat, verifica byte-level si repara o singura data
     DUPA ultima scriere.
     Cens obligatoriu **inainte SI dupa** fiecare editare, care trebuie sa ramana identic:
     `od -An -tx1 <fisier> | tr ' ' '\n' | grep -v '^$' | awk '$1>"7f"' | sort | uniq -c`. Atentie
     la sens: la stricare censul **CRESTE**, nu scade - un octet cp1250 devine 3 octeti `EF BF BD`
     (U+FFFD) la o re-encodare UTF-8 gresita; cauta explicit secventa `EF BF BD`, nu doar tiparul
     generic de mojibake `C3`/`C4`/`C5`/`C8` + octet de continuare (acela da fals-pozitiv pe text
     UTF-8 legitim sau pe comentarii intr-o alta limba, deja intalnite in cod). Verificare veche
     (orice octet >=0x80, utila cand cauti pozitia exacta): `perl -ne 'print "$.\n" if
     /[\x80-\xFF]/' <fisier>`; reparare (pt. `0xBA`): `perl -e
     'binmode(STDIN);binmode(STDOUT);local $/;$_=<STDIN>;s/\xEF\xBF\xBD/\xBA/g;print' < f > f.tmp`.
     `EF BF BD` nu spune ce caracter s-a pierdut - toate diacriticele devin la fel; ia octetul corect
     per pozitie din `svn cat <fisier>` (necorupt) sau din git history (`git cat-file blob
     <commit>:<cale>`, **din Bash, niciodata cu `>` din PowerShell 5.1** - adauga BOM si
     re-encodeaza) inainte sa inlocuiesti - o inlocuire oarba cu `0xBA` strica `a`/`t` cu caciula
     (`0xE3`, `0xFE`) din alte fisiere;
   - adaugi/rearanjezi controale pe formulare sau coloane in grid -> `conventie_ux_formulare.md`;
   - grid needitabil pe formular cu 2+ grid-uri -> `capcana_grid_controlsource.md`;
   - adaugi o coloana intr-un grid deja livrat (ordinea din clasa e neutralizata de
     preferintele salvate per utilizator) -> `capcana_grid_preferinte_utilizator.md`;
   - `GO` pe un `Recno()` capturat/primit ca parametru -> `conventie_go_recno.md`;
   - `ALTER TABLE` pe cursorul intors de `goExecutor.oExecute()` -> `conventie_goexecutor_alter_table.md`;
   - testare UI / prin MCP -> `testare-ui-vfp.md`, `testare-vfp-mcp.md`;
   - garzi pe valori NULL din Oracle -> `conventie_null_vfp.md`;
   - export date din Oracle -> `oracle_export.md`;
   - actualizarea ROA nu se finalizeaza (job update, PACK_UPDATE) -> `depanare-pack-update.md`;
   - modifici schema Oracle (tabele/view-uri/pachete) -> `scripturi-migrare-db.md`.
8. Eroare raportata de utilizator: nu analiza statica indelungata — scrie intai un test care o
   reproduce pe fluxul real; el da cauza si confirma remedierea. Analiza statica doar cat sa stii
   ce sa pui in test.
9. Context sesiune principala: la peste **250k** salveaza contextul intr-un handoff pe disc, il
   predai unei sesiuni noi si te opresti. Limita maxima absoluta: **275k**. Nu estima - masoara:
   hook-ul din `monitorizare-context.md` anunta pragul la fiecare mesaj.
10. Fisier de progres MASTER per proiect (`docs\progres.md`): la zi pe tot parcursul, nu doar la
    predare — stare curenta, facut/testat, ipoteze excluse (cu dovada), ce urmeaza, fisiere atinse,
    comenzi de rulat. O sesiune noua porneste de acolo, fara sa reia investigatia. E ajutor de
    predare, nu documentatie: dupa commit, cu toate sarcinile terminate, se sterge.
11. La final de lucrare/cercetare: **propune** actualizarea documentatiei — `COMUN\docs\` daca e
    comun tuturor aplicatiilor, `docs\` al proiectului daca e specific (plus `inventar-comun.md`,
    regula 3). Doar relevant si reutilizabil (80/20): flux ascuns, capcana, procedura/tabela cheie
    — nu tot ce ai atins, nu verbose. Cateva randuri; propui, nu scrii din oficiu.
    O notita = regula + strictul de context ca sa fie aplicabila: fara cazul particular in care ai
    gasit-o, fara simptomele lantului de erori, fara ce se deduce din cod (cititorul stie deja).
12. Revizuire periodica a documentatiei (`COMUN\docs\`, `docs\` al proiectului, inclusiv acest
    fisier): compacteaza pastrand semantica — taie ce se deduce din cod, exemplele repetate,
    istoricul, tot ce nu mai schimba o decizie. Scopul: docs + reguli sa ocupe cat mai putin context
    la incarcare. Propui rezultatul, nu rescrii din oficiu; nu pierzi nicio regula/capcana, doar
    cuvintele in plus. Fisierele de reguli/conventii se completeaza doar cu ce e super-util,
    simplu si concis. Cadenta o da hook-ul din `monitorizare-context.md` (marker la 30 de zile).