comun/docs/reguli_lucru.md

Reguli de lucru agent (comune proiectelor ROA VFP)

0. Contextul sesiunii principale: te opresti la maxim 250k si salvezi progresul. Nu e optional si nu se negociaza cu "mai termin o banda". La 250k opresti lucrul, scrii in fisierul de progres starea exacta - ce e gata si testat, ce e scris dar neverificat, ce fisiere sunt lasate intr-o stare intermediara (in special text .vc2/.sc2 fara write-back in binar) si care e primul lucru de facut - si predai unei sesiuni noi. Limita absoluta 275k. Nu estima contextul, masoara-l (monitorizare-context.md); daca nu ai masuratoare, opreste-te mai devreme, nu mai tarziu. Orchestrarea multor benzi paralele consuma context mai repede decat pare: fiecare raport de agent, fiecare verificare si fiecare decizie se aduna.

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. Scara (ponytail), te opresti la prima treapta care tine - se aplica si de subagenti, nu doar de sesiunea principala: (1) trebuie sa existe? nevoie presupusa, nu ceruta = nu se scrie, se spune intr-un rand; (2) exista deja in cod (inventar-comun.md, COMUN\, clasa/procedura din acelasi modul)? refoloseste; (3) o face limbajul (VFP, SQL Oracle) sau o biblioteca deja incarcata in roacont.prg? foloseste-o - dependinta noua, niciodata pentru ce tin cateva linii; (4) intra intr-o linie? o linie; (5) abia apoi minimul care merge. Scara scurteaza SOLUTIA, niciodata cititul: intai urmaresti fluxul real prin toate fisierele atinse, apoi alegi treapta. Diff mic in locul gresit nu e economie, e a doua eroare. La eroare: repari cauza in functia comuna prin care trec toti apelantii (-Grep pe apelanti inainte de a edita), nu doar calea din raport - o garda intr-un loc e diff mai mic decat o garda in fiecare apelant, si nu lasa fratii stricati. Interzis din oficiu: clasa/interfata cu o singura utilizare, optiune de configurare pentru o valoare care nu se schimba, schele "pentru mai tarziu", generalizare pentru un al doilea caz care nu exista. Nu se simplifica NICIODATA: validarea datelor venite din exterior (XML eFactura, import, raspuns web), tratarea erorilor care pot pierde date, drepturile de utilizator, si ce s-a cerut explicit. Scurtatura deliberata cu plafon cunoscut (blocare globala, scanare O(n2), euristica naiva) se marcheaza cu un singur comentariu *!* ponytail: <plafonul> - <cum se creste daca deranjeaza>; e singura exceptie de la regula 2, care interzice justificarile in cod. 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: skill roa-vfp-headless-test (headless si UI; criteriile lui blocheaza "gata"). 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, cautare in binare: skill roa-vfp-text-edit (cache, cp1250 byte-safe, fidelity-check si membrii noi sunt in procedura lui). 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 -> skill roa-vfp-text-edit (el detine procedura; criteriile lui blocheaza "gata");
   • adaugi o PROPRIETATE sau o METODA noua intr-o clasa .vc2/.sc2 -> skill roa-vfp-text-edit (membrul nou si *p:/*m: sunt in procedura lui; criteriile lui blocheaza "gata");
   • 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 -> skill roa-vfp-go-recno (el detine procedura; criteriile lui blocheaza "gata");
   • ALTER TABLE pe cursorul intors de goExecutor.oExecute() -> conventie_goexecutor_alter_table.md;
   • testare UI -> skill roa-vfp-headless-test (acopera si testul headless; criteriile lui blocheaza "gata");
   • 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 -> skill roa-vfp-null-guards (el detine procedura; criteriile lui blocheaza "gata");
   • procedura PL/SQL cu SELECT ... INTO chemata din VFP (linii pierdute tacut) -> skill roa-oracle-sqlexec-no-data (el detine procedura; criteriile lui blocheaza "gata");
   • export date din Oracle -> skill roa-oracle-migration (reexportul sursei de pachet e in procedura lui; criteriile lui blocheaza "gata");
   • actualizarea ROA nu se finalizeaza (job update, PACK_UPDATE) -> skill roa-oracle-diagnostic (acopera si spatiul plin; criteriile lui blocheaza "gata");
   • modifici schema Oracle (tabele/view-uri/pachete) -> skill roa-oracle-migration (scriere + publicare scripturi; criteriile lui blocheaza "gata");
   • inrolezi un calculator nou sau un proiect nou in fluxul git-text, expui skill-urile pe masina sau aplici backstop-ul de rutare -> skill roa-onboarding (el detine procedura; criteriile lui blocheaza "gata").

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.