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:

```powershell
$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 + 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.

## 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