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.

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 + 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. 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 regenerata cu git_sync.ps1, inainte de write-back cu txt2vcx.ps1.

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.

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