roacont/CLAUDE.md

CLAUDE.md

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

What this is

ROACONT ("ROA Financiar Contabilitate") is a Visual FoxPro 9 desktop accounting application, one product in the ROA business-software suite built by ROA Romfast SRL. It is a thick client: VFP source (.prg, .scx, .vcx, .mnx, .frx) compiled to an .exe, talking to an Oracle backend over ODBC/native connections. There is no web front-end and no package-manager-based build.

This directory (D:\ROA\ROACONT) is one working copy inside a much larger D:\ROA tree that holds dozens of sibling ROA products (ROAGEST, ROACASA, ROAAUTO, ROAMANAGER, ROAEFACTURA, ROASAL, etc.) plus a suite-wide shared library at D:\ROA\COMUNROA. Changes to shared code can ripple into other products — see "Shared code" below.

Version control

This is primarily an SVN working copy (svn info → ^/ROACONT/Trunk, repository root http://svnroa:3001/svn/ROA). Use svn status, svn diff, svn commit, svn log, etc. for the day-to-day legacy workflow.

A git mirror also runs in parallel, pushed to gitea.romfast.ro:romfast/roacont.git. SVN remains the "live" source of truth; git is synced to it manually, not the other way around. .svn/ is git-ignored. COMUN/ is excluded from this repo's git (see .gitignore) because it's shared by every ROA product and is versioned by its own separate git repo, gitea.romfast.ro:romfast/comun.git (same remote used by ROAACNPRO and other siblings) — run git commands for COMUN/ from inside that directory, not from the ROACONT root.

Git tracks the FoxBin2Prg text versions of the VFP binaries (.vc2/.sc2/.fr2/.mn2/.lb2/.pj2/.dc2/.db2), generated in-tree next to each binary — not the binaries themselves. The binaries and regenerable indexes (.cdx/.dcx) are git-ignored (SVN stays the EOL authority), so git diffs are readable text. Refresh those text versions with git_sync.ps1 (folder-mode recursive over the whole tree incl. COMUN\, incremental):

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

Run it at the start of every session and before any git commit so the text matches the binaries. It converts in a temp staging area and copies back only the text (never touches the SVN working-copy binaries), continues past per-file failures, and exits nonzero on any failure: do not commit while git_sync reports unexplained failures. Then search the .??2 files in-tree with Grep (e.g. PROCEDURE do_salvare), citing file:line.

Editing: write-back text→binary via txt2vcx.ps1 is supported only for .vc2/.sc2 (vcx/scx); .frx/.mnx/.lbx/.pjx/.dbc/.dbf are editable only in the VFP IDE (no write-back). See D:\ROA\UTIL\foxbin2prg\CLAUDE.md and COMUN\docs\flux-editare-vfp-text.md.

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\ROACONT', '-ProjectRoot', 'D:\ROA\ROACONT', '-IndexFile', 'D:\ROA\_vfp_textcache\roacont\_symbols.tsv')

powershell -ExecutionPolicy Bypass -File $s @c -Grep '<expression>' -CodeOnly   # hits labeled class.method, code only
powershell -ExecutionPolicy Bypass -File $s @c -Where '<file>.vc2:<line>'      # who owns this line
powershell -ExecutionPolicy Bypass -File $s @c -Find '<name>'                  # where it is DEFINED
powershell -ExecutionPolicy Bypass -File $s @c -Class '<class name>'           # 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: COMUN\docs\cautare_vcx_vct.md.

Orphan cleanup: on each full run git_sync deletes .??2 text whose binary was removed from SVN (and .db2 whose table left the per-project list) and reports it, so git records the deletion.

SVN ignores the .??2 files via global-ignores in the machine's local Subversion config (%APPDATA%\Subversion\config, [miscellany]), together with *.dbf.cfg. Limitation: global-ignores only covers unversioned files — if a .??2 ever gets svn add-ed, remove it with svn rm --keep-local. The .dbf.cfg files (per-table export config that makes .db2 carry data, not just structure) are committed to git but sit in SVN global-ignores.

Branching (git)

Two lanes in the git mirror: main receives ONLY sync SVN rN commits, made from a clean tree (right after svn update, before local work); Claude works on a branch claude/<subiect> and commits only there, so git diff main..claude/<subiect> shows exactly and only Claude's work. The branch closes once the changes land in SVN (user runs svn commit).

Full model and hygiene rules: COMUN\docs\fluxul_svn_git.md.

Building / running

There is no CLI build tool. The project is compiled from inside the Visual FoxPro 9 IDE:

• Project file: roacont.PJX / roacont.PJT (open in VFP, then Project > Build / Rebuild to produce roacont.exe).
• Every .prg/.scx/.vcx/.mnx source file has a compiled sibling (.FXP/.SCT/.VCT/.MPR). Always edit the source file, never the compiled binary companion — the binaries are regenerated by the VFP compiler and are not meant to be hand-edited or diffed.
• .BAK files scattered throughout Programe/, Clase/, etc. are VFP's own editor backups, not something to restore from manually.
• There are no automated tests. COMUN/utile/Teste/test.prg and teste_roacont.prg are ad hoc manual test scripts, not a test runner.

Entry point and startup flow

Programe/roacont.prg is the application entry point (PARAMETERS tparam — a semicolon- delimited connection string when launched by the ROA "Start" launcher). It:

1. Sets the VFP environment (SET PATH, SET CLASSLIB/SET PROCEDURE ... ADDITIVE) — this is effectively the dependency-injection root: dozens of .vcx class libraries and .prg procedure files are registered here in a fixed order, and later code assumes they're all loaded. New shared .prg/.vcx files must be registered here to be reachable app-wide.
2. Verifies the license/serial (PORNIRE() — disk serial + comdir.snr + registry key check) and that the app was launched via the suite's start mechanism (Verific_Start), unless a local debug.txt marker is present.
3. Reads settings.ini (via getini/setini, COMUN ini helpers) for local machine config (report behavior, keepalive interval, error-reporting host, locale).
4. Instantiates global singleton objects that the rest of the app depends on as PUBLIC/module globals: goConn (Oracle connect/disconnect wrapper), goExecutor (SQL exec wrapper with error handling), goExport (report/Excel export), goLocale (i18n), poLog/goLog (Log_Mesaje logging object), goApi/goMyXMLHTTP (remote error/update HTTP calls).
5. Sets ON ERROR ErrorHandler(...) and ON SHUTDOWN handlers — uncaught errors are logged via goLog, posted to a remote error endpoint (goMyXMLHTTP.postError, host from settings.ini [errors] host), and shown via AMESSAGEBOX.
6. Creates the main cApplication object (goApp) and shows the login form (COMUN\ferestre\frm_login.scx), which resolves the target company (goFirma), Oracle schema (gcS, e.g. 'CONTAFIN'), and fiscal period (gnAn/gnLuna) before handing off to the main menu (Meniuri\cont2000.mpr).

Key long-lived globals to know when reading code: gcS (current Oracle schema/company), gnAn/gnLuna (current fiscal year/month), goFirma/gnIdFirma (current company object/id), gcAppPath/DIRGEN (app root paths), glLunaInchisa (period-closed flag that disables edit UI).

Directory layout

• Programe/ — top-level .prg business-logic modules registered via SET PROCEDURE ... ADDITIVE in roacont.prg (e.g. proceduri.prg, oproceduri_*.prg per functional area: incasari, casademarcat, conversie, decont, import, facturare, etc.).
• Clase/ — .vcx/.vct VFP class libraries: base UI classes (cont2000, contab, baza), Oracle-domain classes prefixed o* (oparteneri, ovanzcump, ocasabanca, orapoarte_*, oconversii, saft_d406, anaf_efactura, ...).
• Ferestre/ — .scx/.sct forms (data entry screens, dialogs).
• Meniuri/ — .mnx/.mnt/.mpr menus; one .mpr per top-level menu context (cont2000.mpr is the main menu; casa1, banca1, capitaluri1...8, etc. are module-specific submenus/menus).
• Rapoarte/ — .frx/.frt report definitions (balances, journals, declarations like rap_declaratia100, D394/D406/SAF-T exports, invoices).
• Include/ — third-party OCX controls and reference docs (SAF-T guide, D394 spec).
• Initializari/ — .tmpl templates for generated XML/receipt files.
• Locale/ — DBF-based i18n tables (locale*.dbf) and locale.dbc database container; Romanian is the built-in default (see Localization below).
• DATE/ — local machine/company option tables (Optiuni_FIRMA/LOCAL/PROGRAM.dbf).
• Grafice/ — icons/bitmaps used by forms and toolbars.
• Help/ — DBF-based in-app help content tables.
• Alte/ — scratch/example data files (bank statement exports, import templates); not part of the shipped app.
• Root .sql files (roacont1/2/3.sql, anaf_efactura.sql, vanzari*.sql, mfinante.sql) — hand-run Oracle DDL/DML migrations, not applied automatically.
• changelog_roacont.txt, bug_registru.txt — human-maintained change logs (see Changelog convention below).
• versiune_db.txt — a manually bumped YYYY_MM_DD_NN marker used to track the last applied DB migration.

Shared code (COMUN/ vs. COMUNROA)

• COMUN/ inside this project is ROACONT's local copy of shared assets (clase, ferestre, programe, rapoarte, meniuri, utile), mirroring the same substructure as the app root. COMUN/utile/ holds cross-cutting utilities: web (WWUTILS.PRG, WWAPI.PRG, wwhttp, http/xml helpers), excel, hpdf (PDF export), nfjson/nfXml, calendar, ctl32, email, chatbot, GridExtras.
• D:\ROA\COMUNROA (outside this working copy) is the suite-wide shared library referenced from roacont.prg's SET PATH (...COMUNROA\) and used by every sibling ROA product — treat edits there as cross-project and higher-blast-radius than edits under this project's own COMUN/.
• COMUN/Drepturi utilizatori/ holds the per-product SQL that defines user permission objects (subfolders per product: ROACONT, ROAGEST, ROACASA, ROAAUTO, ...) and instructiuni drepturi.txt, which documents the permission-object conventions used on forms (ntip values 0–5 for view/report/register/ledger-or-partner/view/custom access levels, verifica_drepturi(...) gating, cbuton1..4 button wiring, glLunaInchisa read-only lock).

Changelog convention

changelog_roacont.txt is a flat file of HTML-comment blocks, newest first, one per release:

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

:tag:
  Description of the change.
-->

Regula de continut: changelog-ul e pentru utilizatori — se scrie doar ce vede utilizatorul, scurt si compact. Erorile introduse si reparate in aceeasi versiune nelivrata nu se trec (clientul nu le-a vazut niciodata); intrarea versiunii curente se rescrie, nu se acumuleaza. Changelog-ul insoteste livrarea unui .exe: o modificare numai de baza de date (script din SCRIPTURI_CLAR), fara versiune noua de executabil, nu intra in changelog.

Tags in use: :nou: (new feature), :modificare: (change/fix to existing behavior), :eroare: (bug fix), :adaugare: (addition). Version numbers increment per entry (current series is 2.11.x). When asked to log a change, follow this exact format/tag set rather than inventing a new one. In-code change comments follow a similar per-block convention: *!* DD.MM.YYYY followed by *!* author.name and a short description, directly above the code being changed — preserve this style when editing existing modules.

Localization

gcLocale defaults to 'Romana', in which case goLocale is a Locale_dummy pass-through (no translation lookup). Any other locale value loads the real Locale class (Locale.vcx) backed by the locale*.dbf tables under Locale/. Most in-app strings and comments are Romanian; 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, write-back si teste imediat, aprobare inainte de commit), 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. Depanare detaliata: COMUN\docs\depanare_testare_vfp.md.

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

Preferintele lui Marius pentru sesiunile pe acest proiect:

• Orchestrare pe misiuni lungi: niciodata un singur subagent care acumuleaza context pe multe sarcini inlantuite — sesiunea principala orchestreaza subagenti proaspeti per sarcina (prag: max ~200-250k tokens per subagent, apoi handoff + agent nou), cu handoff compact pe disc; regula comuna tuturor proiectelor ROA: COMUN\docs\orchestrare-subagenti.md.
• Delegare: modificarile de cod de volum/rutina (aplicarea unei propuneri aprobate din docs/, editari pe versiunile text .??2 + write-back cu txt2vcx.ps1, actualizari de documentatie, rulari de teste) se delega catre subagenti Sonnet care lucreaza in background (Agent tool cu model: sonnet, lane-uri paralele unde e posibil), iar sesiunea principala doar orchestreaza si monitorizeaza: imparte planul pe lane-uri, transmite constatarile intre agenti, verifica rezultatele (diff, teste, fidelity) si intervine direct doar la deblocari (procese agatate), decizii si verificari.
• Fara commit fara review: nu da commit (git sau svn) din proprie initiativa pe modificari de cod — Marius vrea intai sa vada diff-ul, ca fisier in docs/. Pentru binarele VFP (.vcx/.scx), diff-ul lizibil se face pe forma text .vc2/.sc2. Write-back-ul cu txt2vcx.ps1 si testele se fac imediat dupa editare; doar commit-ul asteapta aprobarea diff-ului (regula 1 din COMUN\docs\reguli_lucru.md).

Stil de raspuns: scurt si concret

Marius vrea raspunsuri clare, concise, fara vorbarie. Regula, nu preferinta.

• Starea si ce urmeaza, nu povestea. Ce e gata, ce e stricat, ce trebuie decis, ce urmeaza — in liste scurte, cu fisier si linie. Fara reconstituirea drumului pana la rezultat.
• Fara naratiune de proces: ce a raportat fiecare agent, cine ce a corectat, cum au fost coordonate benzile. Intra in docs/, nu in raspuns.
• Fara laude si fara reluari. Nu repeta ce s-a spus deja in conversatie.
• Detaliile tehnice lungi (dovezi, iesiri de test, metodologie) se scriu in fisier si se trimite la el, nu se copiaza in raspuns.
• Cand e ceva de decis: enunta decizia si optiunile in cateva randuri, cu recomandarea ta.

Formatul obligatoriu al raspunsului, in aceasta ordine, maxim cateva randuri fiecare:

1. Am facut: ce e gata (fisier:linie).
2. Urmeaza: ce fac mai departe.
3. De la tine: intrebarea, clar si simpla, cu recomandarea mea.

Explicatiile, dovezile si descoperirile colaterale merg in docs/, cu un link. Nu se reia in raspuns rationamentul, nu se explica de ce a fost greu, nu se justifica alegerile decat daca sunt cerute.

gstack

Foloseste skill-ul /browse din gstack pentru tot browsing-ul web; nu mai folosi tool-urile mcp__claude-in-chrome__*.

Skill-uri disponibile din gstack: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /retro, /investigate, /document-release, /document-generate, /codex, /cso, /autoplan, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn.

Skill routing

When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill.

Key routing rules:

• Product ideas/brainstorming → invoke /office-hours
• Strategy/scope → invoke /plan-ceo-review
• Architecture → invoke /plan-eng-review
• Design system/plan review → invoke /design-consultation or /plan-design-review
• Full review pipeline → invoke /autoplan
• Bugs/errors → invoke /investigate
• QA/testing site behavior → invoke /qa or /qa-only
• Code review/diff check → invoke /review
• Visual polish → invoke /design-review
• Ship/deploy/PR → invoke /ship or /land-and-deploy
• Save progress → invoke /context-save
• Resume context → invoke /context-restore

Regulile complete de lucru ROA (livrare, comentarii, modificari minime, testare, delegare): COMUN\docs\reguli_lucru.md. Punctul 7 ruteaza fiecare zona atinsa.

Backstop de rutare: cand atingi o zona de mai jos, incarca skill-ul care o detine (el are procedura si criteriile care blocheaza "gata"); docurile sunt doar referinta conditionata a skill-ului.

• editezi .vc2/.sc2/.prg cu diacritice, cauti in .vcx/.scx, adaugi membri de clasa -> skill roa-vfp-text-edit
• rulezi sau depanezi teste headless ori UI -> skill roa-vfp-headless-test
• commit / svn update / roa_sync in COMUN -> skill roa-git-svn-commit
• scrii sau publici scripturi de migrare Oracle, reexporti un pachet -> skill roa-oracle-migration
• actualizarea ROA nu se termina sau tablespace plin -> skill roa-oracle-diagnostic
• acces la un Oracle de productie (tunel SSH + TNS + DSN) -> skill roa-oracle-production-access
• garzi pe valori NULL din Oracle in VFP -> skill roa-vfp-null-guards
• GO pe un Recno() capturat sau primit ca parametru -> skill roa-vfp-go-recno
• procedura PL/SQL cu SELECT ... INTO apelata din VFP (randuri pierdute tacut) -> skill roa-oracle-sqlexec-no-data
• inrolezi un calculator nou sau un proiect nou in fluxul git-text / expui skill-urile pe masina / aplici backstop-ul de rutare -> skill roa-onboarding