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.
   Test pe cursor derivat din view/`select *` Oracle: foloseste structura REALA (cu nume lungi),
   nu un cursor restrans la cateva campuri; un cursor cu nume <= 10 caractere trece la ALTER TABLE
   si ascunde eroarea 1115.
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");
   - creezi sau editezi un raport `.frx`/`.frt` (structura DBF, band-uri, grupare, totaluri, preview) -> skill roa-vfp-frx-report (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");
   - rulezi sau depanezi workflow-ul Archon `roa-fix` -> `archon_capcane.md`;
   - cerere HTTP din VFP catre romfast.ro (WinHTTP/ServerXMLHTTP) -> `http_romfast_user_agent.md`;
   - 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).
14. **Cand o decizie admite mai multe variante si incepi o investigatie ca sa alegi singur,
    opreste-te si intreaba utilizatorul** (ask-user) cu variantele clare si o recomandare. Decizia
    lui e mai rapida si mai corecta decat o investigatie lunga; o varianta gresita costa o runda,
    o investigatie gresita costa o sesiune. Valabil si pentru subagenti: cand nu stii, intrebi,
    nu ghici. Extinderea completa (interactiune, livrare, cautare):
    `stil_interactiune_cautare.md`.
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.