roafacturare/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

ROAFACTURARE is a Visual FoxPro 9 desktop invoicing application, one product in the ROA business-software suite built by ROA Romfast SRL. Thick client: VFP source (.prg, .scx, .vcx, .mnx, .frx) compiled to roafacturare.exe, talking to an Oracle backend. No web front-end, no package-manager-based build.

This directory (D:\ROA\ROAFACTURARE) is one working copy inside the larger D:\ROA tree that holds the sibling ROA products (ROACONT, ROAGEST, ROAIMOB, ROAACNPRO, ...) plus the suite-wide shared library D:\ROA\COMUNROA.

Version control

Primarily an SVN working copy (^/ROAFACTURARE/Trunk, repository root http://svnroa:3001/svn/ROA) — use svn status, svn diff, svn commit for the day-to-day legacy workflow. A git mirror runs in parallel (gitea.romfast.ro:romfast/roafacturare.git), synced manually from SVN; SVN stays the source of truth.

Git tracks the FoxBin2Prg text versions of the VFP binaries (.vc2/.sc2/.fr2/.mn2/.lb2/.pj2), generated in-tree next to each binary — not the binaries themselves. Refresh them with git_sync.ps1 at the start of every session and before any git commit:

powershell -ExecutionPolicy Bypass -File D:\ROA\UTIL\foxbin2prg\git_sync.ps1 -ProjectRoot D:\ROA\ROAFACTURARE

Then search the .??2 files in-tree with Grep, citing file:line. Write-back text->binary via txt2vcx.ps1 is supported only for .vc2/.sc2; .frx/.mnx/.lbx/.pjx/.dbc/.dbf are editable only in the VFP IDE. See D:\ROA\UTIL\foxbin2prg\CLAUDE.md; pentru editarea text->binar foloseste skill-ul roa-vfp-text-edit (detine procedura si write-back-ul).

Grep can't tell which class/method a hit inside a .vc2 belongs to (the class header may be thousands of lines above it, and ~2/3 of the file is properties/metadata). vfp_symbols.ps1 indexes the line range of every class/method/procedure and labels hits with their owner — use it before any txt2vcx.ps1 edit to get the exact line range of the method you are changing. Its built-in defaults target ROAACNPRO, so always pass this project's paths:

$s = 'D:\ROA\UTIL\foxbin2prg\vfp_symbols.ps1'
$c = @('-CacheRoot', 'D:\ROA\ROAFACTURARE', '-ProjectRoot', 'D:\ROA\ROAFACTURARE', '-IndexFile', 'D:\ROA\_vfp_textcache\roafacturare\_symbols.tsv')

powershell -ExecutionPolicy Bypass -File $s @c -Grep '<expresie>' -CodeOnly   # hits labeled class.method, code only
powershell -ExecutionPolicy Bypass -File $s @c -Where '<fisier>.vc2:<linie>'  # who owns this line
powershell -ExecutionPolicy Bypass -File $s @c -Find '<nume>'                 # where it is DEFINED
powershell -ExecutionPolicy Bypass -File $s @c -Class '<nume_clasa>'          # inheritance chain + methods

The index (_symbols.tsv) rebuilds itself when the text is newer, so refresh the text first — it can't see IDE edits that were never converted. Full search guide: skill roa-vfp-text-edit (cautarea in binare e in procedura lui).

COMUN/ is excluded from this repo's git — it is shared by every ROA product and versioned by its own git repo, gitea.romfast.ro:romfast/comun.git. Run git commands for COMUN/ from inside that directory, and treat any change there as cross-project.

Building / running

No CLI build tool. Compiled from inside the VFP 9 IDE: open roafacturare.PJX, then Project > Build / Rebuild. Entry point is Programe/roafacturare.prg (PARAMETERS tparam — a connection string passed by the ROA "Start" launcher); it sets the VFP environment (SET PATH, SET CLASSLIB, SET PROCEDURE ... ADDITIVE), so new shared .prg/.vcx files must be registered there to be reachable app-wide. Always edit the source file, never its compiled sibling (.FXP/.SCT/.VCT/.MPR). No automated tests.

Directory layout

Programe/ top-level business-logic modules · Clase/ .vcx class libraries · Ferestre/ and Formulare/ .scx forms · Meniuri/ menus · Rapoarte/ .frx reports · Locale/ DBF-based i18n · COMUN/ this project's copy of the shared assets (clase, ferestre, programe, rapoarte, utile) · Utile/, Include/, Grafice/, Ajutor/, Mesaje/ support assets. versiune_db.txt is a manually bumped YYYY_MM_DD_NN marker for the last applied DB migration.

Changelog convention

changelog_roafacturare.txt is a flat file of HTML-comment blocks, newest first:

<!--
DD/MM/YYYY
ROAFACTURARE - X.Y.Z

:modificare:
  <what changed>
-->

Tags: :nou: (new feature), :modificare: (change), :eroare: (bug fix), :adaugare: (addition). Bump MAJOR.MINOR.PATCH per entry (current series 2.11.x).

Comments

Change history goes in the file header only, never inline — one cumulative entry per feature (*!* DD.MM.YYYY / *!* author / *!* what it does, 1-2 sentences), rewritten rather than appended on revisit. Same in .prg, in .sql migration scripts and in PL/SQL.

In-code comments are short and strictly functional, and only where they earn their place: a branch or a filter that isn't self-evident. One line as a rule. No references to plans, stories, decisions, bug reports or docs/ reports, no justification of the choice made, no history of the change, no dates or authors on new code. Full rule and the list of prohibitions: COMUN\docs\reguli_lucru.md, point 2.

Localization

Romanian is the built-in default. Keep new user-facing strings and code comments in Romanian to match the existing codebase unless told otherwise.

Reguli de lucru si testare

Inainte de orice modificare de cod sau testare, citeste COMUN\docs\reguli_lucru.md. Nu e optional si nu e doar context: contine regulile de livrare (diff ca fisier + aprobare inainte de write-back), comentariile (max o linie), modificarile minime, harnessul de testare headless si — la punctul 7 — lista de conventii obligatorii per zona atinsa (encoding cp1252 la editarea .vc2/.sc2, UX formulare/griduri, GO pe Recno(), goExecutor + ALTER TABLE, testare UI, export Oracle). Fisierul e index: urmeaza linkurile relevante pentru sarcina curenta. Punctul 7 al acelui fisier ruteaza fiecare zona atinsa la skill-ul care o detine (COMUN\skills\), iar skill-ul - nu docul - detine procedura. Testare si depanare: skill roa-vfp-headless-test.

Mod de lucru: delegare catre subagenti + review inainte de commit

REGULA OBLIGATORIE (ceruta explicit de Marius, 26.08.2026): orice investigatie, modificare de cod, editare de fisiere, rulare de teste sau verificare se deleaga unui SUBAGENT (Task tool). Sesiunea principala DOAR orchestreaza si verifica rezultatele subagentilor; nu lucreaza direct pe fisiere, nu ruleaza suite, nu editeaza cod. Inca de la prima sarcina a unui bloc, nu dupa ce ai acumulat context.

• Predarea contextului e OBLIGATORIE, si pentru sesiunea principala, si pentru subagenti. Nu e o optimizare, e o conditie de corectitudine. Declansatoare: ~50% din fereastra (sesiunea principala / orchestrator), ~200-250k tokens (subagent), anuntul de compactare automata al harness-ului, semnalul utilizatorului, sau terminarea unui bloc de lucru. La oricare dintre ele, in ordine: opreste lucrul (adu editarile in curs la o stare consistenta pe disc, nu incepe nimic nou) -> scrie handoff-ul PE DISC (docs\handoff_<subiect>.md, nu doar in mesaj) -> confirma in doua randuri ce ramane si ce e intr-o stare periculoasa (fisier editat fara write-back, tranzactie deschisa, proces viu, date de test consumate) -> opreste-te; blocul urmator il ia un agent proaspat. "Mai am putin" nu e motiv de amanare — exact acolo se pierd lucrurile. Un subagent care se apropie de prag anunta singur, nu asteapta sa fie oprit. Procedura completa si ce intra in handoff: COMUN\docs\orchestrare-subagenti.md, sectiunea Regula zero.
• Orchestrare pe misiuni lungi: niciodata un singur subagent care acumuleaza context pe multe sarcini inlantuite — sesiunea principala orchestreaza subagenti proaspeti per sarcina, cu handoff compact pe disc.
• Delegare: modificarile de cod de volum/rutina (aplicarea unei propuneri aprobate din docs/, editari pe versiunile text .??2 + write-back, actualizari de documentatie, rulari de teste) se delega catre subagenti Sonnet care lucreaza in background (Agent tool cu model: sonnet), iar sesiunea principala doar orchestreaza si verifica rezultatele.
• Fara commit fara review: nu da commit (git sau svn) din proprie initiativa pe modificari de cod — diff-ul se livreaza intai ca fisier in docs/, iar commit-ul vine dupa aprobare.

Executie continua a unui plan (mandat permanent, Marius, 30.08.2026)

„vreau sa continui toate stories, cu commit dupa fiecare, si handoff la limita de context”

Cand lucrezi la un plan cu mai multe stories, mandatul e valabil pana la revocare explicita:

1. Toate stories, in ordinea de dependente din fisierul de executie al planului — fara oprire dupa fiecare ca sa intrebi „continuam?”.
2. Commit dupa fiecare story, pe branch-ul de lucru, in repo-ul potrivit (cod COMUN din COMUN\, restul din radacina proiectului). Review inainte de commit, dar fara a mai cere aprobare — aprobarea e data pentru intreg lantul. Fara push; SVN si merge-ul raman la Marius.
3. Handoff la limita de context — vezi Regula zero de mai sus. Fisierul de stare viu al planului se actualizeaza dupa FIECARE story inchisa, nu la final.

Corolar cand Marius nu poate testa manual: pentru fiecare story al carui criteriu oficial de „gata” e o proba manuala UI, se proiecteaza si o proba automata de paritate (headless sau prin vfp_ui_harness.ps1), iar ce ramane obligatoriu manual se inregistreaza explicit ca datorie deschisa — nu se declara „gata”.

Ponytail (plugin la nivel de user)

Plugin-ul tert ponytail e activ implicit pe nivelul full la fiecare sesiune si reinjectat in fiecare subagent — nu doar in sesiunea principala. Nu ruleaza retea si nu trimite telemetrie: scrie doar un flag local (~/.claude/.ponytail-active) si citeste ~/.claude/settings.json.

Se pastreaza scara YAGNI/reuse-first (nu scrii ce exista deja in inventar-comun.md, COMUN\programe, COMUN\clase, sau ce face VFP/Oracle nativ) — se suprapune cu regula proiectului de modificari minime, SCOPED.

Ce NU se aplica aici, cu regula proiectului care primeaza (detaliu complet: COMUN\docs\reguli_lucru.md, punctul 3, „Scara ponytail”):

• comentarii ponytail: in cod -> interzise (regula 2); scurtatura si limita ei merg in docs\progres.md, nu inline.
• proba „runnable test / assert self-check” -> script headless (regulile 4 si 8), nu test_*.py.
• „cod intai, maxim trei randuri” -> nu se aplica handoff-urilor, rapoartelor din docs\ si patch-urilor, care sunt output cerut explicit.
• /ponytail-review si /ponytail-audit: delete:/yagni: sunt ipoteze, nu constatari — in COMUN cauti apelantii in tot D:\ROA inainte sa stergi; audit pe tot arborele nu se ruleaza aici.
• nivelul ultra nu se foloseste pe cod legacy partajat.