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. Scara ponytail (plugin activ implicit pe full, injectat si in subagenti; ultra nu se foloseste pe cod legacy partajat): opreste-te la prima treapta care tine - 1) trebuie sa existe? 2) exista deja (inventar-comun.md, COMUN\programe, COMUN\clase) -> refolosesti; 3) o functie VFP nativa o face; 4) se rezolva pe Oracle (view, constrangere, pachet) in loc de cod client; 5) o linie; 6) abia apoi minimul care merge. Scurteaza SOLUTIA, nu cititul - intai urmaresti fluxul real atins. Nu se simplifica niciodata: garzile pe NULL, validarile, tratarea erorilor, drepturile de acces, ce s-a cerut explicit. Abateri obligatorii fata de plugin: (a) fara comentarii ponytail: in cod (regula 2) - scurtatura deliberata si limita ei se noteaza in docs\progres.md, deci /ponytail-debt nu are ce culege aici; (b) proba unei logici noi e un script headless (regulile 4 si 8), nu test_*.py; (c) handoff-urile, rapoartele din docs\ si patch-urile sunt output cerut explicit - regula "cod intai, maxim trei randuri" nu li se aplica; (d) /ponytail-review pe diff-ul rundei inainte de commit e util, dar delete:/yagni: sunt IPOTEZE, nu constatari: in COMUN apelantii sunt in toate produsele, deci cauti in tot D:\ROA inainte sa stergi, iar o garda fara caz in datele de test nu e garda moarta (regula 6); /ponytail-audit pe tot arborele nu se ruleaza aici.
4. Testare headless (fara IDE): vfp9.exe -A -T "<script.prg>" <param> din PowerShell. Mediu, sabloane, capcane, depanare: depanare_testare_vfp.md. Rularile intermediare acopera doar familiile de teste atinse de modificarea curenta; suita completa, inclusiv testele de garda pe zonele vecine, se ruleaza doar la rularea finala — garzile exista fiindca schimbarile cad de regula in cod partajat (COMUN), vizibil in toate produsele, dar costul lor nu se plateste la fiecare rulare intermediara. Ideal, doar testele atinse direct (de regula 3-10), nu toata familia. Un test normal dureaza 1-5s — ce umfla o rulare nu e testarea, ci asteptarea unui test atarnat. La rulari intermediare: timeout 90s/test (ce trece de atat e atarnat, nu lent) si pauza 0,5s intre teste, nu implicitul de 12 minute / 3s, rezervat rularii finale unde chiar conteaza sa distingi "atarnat" de "lent". Tinta: o rulare intermediara sta in secunde-minute, nu ore — daca depaseste, lista e prea larga sau timeout-ul prea mare.
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, unde s-urile cu virgula din masina/si contul/transa sunt octetul 0xBA) -> fisierele sunt cp1250 desi antetul FoxBin2Prg declara CPID="1252"; Edit/Write corup TOT fisierul (nu doar linia atinsa), ireversibil, 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. Tabelul complet de octeti, sensul censului la stricare si procedura de recuperare din git/svn -> 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;
   • procedura PL/SQL cu SELECT ... INTO chemata din VFP (linii pierdute tacut) -> capcana_sqlexec_no_data_found.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.