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.
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).