GTI_GERENCIADOR_FISCAL/fiscal/CLAUDE.md

GTI Discovery

Primeira leitura obrigatória, antes de qualquer missão fiscal nova: docs/PROJECT_STATE.md (versões Hub/Agent, migration head de cada branch, status do Reference Data Registry, decisões ADMIN pendentes, o que já foi feito e o que falta, riscos abertos). Mantê-lo atualizado ao final de cada missão que mude esse estado.

This project is strictly read-only. Discovery code must use a database-level read-only account or transaction/driver mode; lexical SQL validation is only defense-in-depth. Discovery code must not perform DML or DDL, modify database objects or permissions, or store credentials and other secrets.

Run the offline tests with:

# Suíte completa canônica (1160+ testes: raiz + Hub + Agent):
python -m pytest tests central/tests agent/tests -q

# Apenas testes unitários offline da raiz:
python -m pytest tests -q

Firebird write policy

Default policy:

• All client/production Firebird databases are STRICTLY READ-ONLY.
• Never perform INSERT, UPDATE, DELETE, DDL, permission changes, or destructive operations against any client/production ERP database unless explicitly authorized in a future policy change.

Explicit development exception:

The following database is a disposable TEST DATABASE and is explicitly authorized for writes:

D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB

For this exact file only, the agent MAY perform:

• SELECT
• INSERT
• UPDATE
• DELETE
• DDL
• transactional tests
• rollback/recovery tests
• destructive development experiments when necessary

This database has external intact backups and can be restored.

Safety requirement:

Before ANY Firebird write, the code must verify that the canonical absolute database path is exactly:

D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB

If the path differs in any way, writes must fail closed.

Never infer write authorization from filename alone. Never enable writes to other Firebird databases.

Secrets:

• credentials remain local in ignored environment files;
• never log, commit, or expose passwords.

Development priority:

• TESTESOFICIAIS.FDB may be modified freely as needed to validate the MVP.
• Do not over-engineer rollback protections for this disposable test database unless they are part of the product behavior being validated.

GTI Fiscal write-target rule

The SGV keeps its fiscal defaults in the canonical product record (C000025); every other routine consumes them. GTI Fiscal therefore writes ONLY to the canonical product record, and only fields whose mapping is proven (docs/SGV_PRODUCT_FISCAL_UI_MAP_V1.json, write_target=true). It never writes to NFCE, NFCE_ITENS, item tables, issued documents or any other transactional/historical table; those are read-only evidence for validation. Company context (UF, CRT) is read from C000004 at run time — never hardcoded.

Local completion mission — exact write allowlist (operator-authorized)

For the "GTI FISCAL LOCAL COMPLETION V1" mission the operator explicitly authorized writes to the disposable COPIES listed, by exact canonical path, in docs/LOCAL_WRITE_ALLOWLIST_V1.json (CONSTRUCAO, MMMODAS, RINCAO, UNIAO under Projeto\Banco\, plus TESTESOFICIAIS.FDB). Authorization is by exact path only — never by directory or .FDB extension. Any other Firebird under D:\PROJETOS\GTISISTEMAS stays strictly READ-ONLY. Writes go through the guarded executor (path allowlist, company-context guard, schema/type/length guard, compare-before-write, rowcount, transaction, audit) and only to C000025 fields whose contract in docs/FISCAL_FIELD_CONTRACT_V1.json has WRITE_ALLOWED=true. This authorization does not extend to production or client databases.

Production deploy rule (Hub)

Normal deploy = powershell -ExecutionPolicy Bypass -File .\scripts\deploy_hub.ps1 [-PublishAgent -Version X] (docs/DEPLOY_HUB.md). Do not recreate ad-hoc deploy scripts (deploy115.py etc.) and do not improvise SSH/docker against 10.0.10.117. The script handles VPN/SSH retry, backup, upload, migrations, rebuild, health, release publish, download verification, and automatic rollback; the real error is in logs/last_deploy_result.json and the log.

Versioning (adopted standard, see docs/VERSIONING.md)

Hub and Agent are versioned and released independently — never assume they share a version number, and never make the Hub's GTI_FISCAL_VERSION bump touch the Agent's own version files (agent/pyproject.toml, the AGENT_VERSION defaults) or vice versa. The panel's "Atualização disponível" already compares an Agent's reported version against the highest PUBLISHED Windows AgentRelease, never against the Hub's version — see docs/VERSIONING.md for the exact mechanism and the current (informal) compatibility matrix.

Permanent mission rules (fiscal completion missions, recorded 2026-09-28)

• No AI/LLM/embeddings, no paid API, no scraping — every rule/decision is derived from real ERP evidence or an explicit, audited operator/ADMIN decision (FiscalContextEntry), never inferred or guessed.
• No Firebird triggers or schema changes, ever, for any discovery/completion mission. All queries against any Firebird database (client, lab copy, or disposable test DB) are read-only unless the exact path is on an explicit, mission-scoped write allowlist (see above) — writes still go only through the guarded executor.
• Deploy only via scripts\deploy_hub.ps1 (see "Production deploy rule" above) — never ad-hoc SSH/docker/psql against 10.0.10.117.
• If the Agent (agent/) changes in a way that affects its runtime behavior: bump the single-source version, build a new installer, validate it in a fresh Windows Sandbox (install, upgrade in-place, identity preserved), and never overwrite an already-published release. A pure version-label sync bump (release/VERSION, pyproject.toml files, the AGENT_VERSION default string) that changes no Agent behavior is not itself an "Agent change" requiring a new installer.
• Never reenroll an existing installation (never mint a new installation_id/token for a machine that already has one) — an in-place upgrade always preserves identity and local SQLite state.
• No remote-execution channel to any client's Agent host, ever (by design — see docs/rtc_auto_apply.md). An Agent version upgrade on a real client machine is always performed by a human operator on-site; the assistant never attempts RDP/WinRM/SSH/PowerShell-remoting into a client host, and never asks for or accepts a production AGENT_TOKEN/admin session credential pasted in chat to work around that — live validation of a real installation, when needed, comes from the operator (a panel screenshot, or a value they read and paste themselves).
• No real client/production data (CNPJ, razão social, product names/descriptions, per-product NCM) is ever published in a location a non-admin can reach (e.g. central/static/). Any evidence artifact referenced from a UI card must either be served through an authenticated ADMIN-only route, or be anonymized (generic client labels, no names/documents/descriptions) before being published as a static file.