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, notele de rezolvare (docs/fix_*.md, docs/fix_*.diff), *.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). 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. Istoricul modificarilor sta DOAR in antetul fisierului (niciodata inline, la fel in .prg, .sql si PL/SQL Oracle): 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. Verificarea a ce se intoarce si modelul de lucru (backlog de story-uri mici): orchestrare-subagenti.md.
7. Conventii obligatorii, de citit cand atingi zona respectiva:
   • editezi .vc2/.sc2 sau .prg cu diacritice (ex. programe\ocautare.prg) -> fisierele sunt cp1250 desi antetul FoxBin2Prg declara CPID="1252"; Edit/Write corup TOT fisierul (nu doar linia atinsa) la fiecare scriere - scrie continut nou strict ASCII. Cens obligatoriu inainte SI dupa fiecare editare (la stricare CRESTE, nu scade): od -An -tx1 <fisier> | tr ' ' '\n' | grep -v '^$' | awk '$1>"7f"' | sort | uniq -c. Tabel de octeti si reparare -> conventie_encoding_cp1252.md;
   • adaugi o PROPRIETATE sau o METODA noua intr-o clasa .vc2/.sc2 -> flux-editare-vfp-text.md, sectiunea "Membri noi de clasa": fara intrarea *p:/*m: in *<DefinedPropArrayMethod> membrul trece fidelity-check-ul, dar VFP nu-l vede si prima salvare din IDE il sterge tacut;
   • 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 -> testare-ui-vfp.md;
   • te conectezi la Oracle pe dev/test, alegi schema sau rulezi un script de pachet -> conventie_mediu_oracle.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).
13. Documente de propuneri/directie: unul singur, final, in COMUN\docs\cercetare\rec_*.md. Materialul de lucru (brief-uri, handoff-uri, variante intermediare, patch-uri) NU se pastreaza; dovezile masurate si scripturile raman in docs\ al proiectului, iar documentul trimite la ele. Structura per propunere, in aceasta ordine: unde (modulul/ecranul + fisier:linie), cum e azi, ce se schimba, ce se castiga (cifra, marcata masurat sau nemasurat), ce risc. Gruparea e pe sectiuni de program, nu pe teme abstracte. masurat = backtest cronologic pe date reale comparat cu ce a confirmat operatorul, nu estimare; orice cifra nemarcata se citeste ca inventata. Se adauga o sectiune de respinse, cu motivul intr-un rand, ca sa nu fie repropuse, si capcanele de masurare platite. INTERZIS: naratiune de proces (cine ce a raportat, cum s-au coordonat benzile), tabele de tip "efort mic/mediu" fara explicatie, liste de etichete tehnice, aceeasi idee in doua fisiere.