Merge pull request #198 from LayoutParser/feat/contrato-linha-vazia-e-progresso

feat: contrato aditivo de linha vazia/degradacao posicional + fases de progresso

Author: elson-vinicius-lopes

.claude/agent-memory/lp-pm/MEMORY.md

@@ -9,3 +9,4 @@
 - [Mapeamento campo TXT<->XML 2026-08-16](project_mapeamento-campo-txt-xml-2026-08-16.md) — issues #137-#141 (guarda-chuva + Fases 0-3), plano de `@lp-architect` pro PBI #128/Epic #126 do front-end.
 - [Bug/gate issues 2026-08-20](project_bug-gate-issues-2026-08-20.md) — #171-#174, 4 TODOs de @lp-architect confirmados no código (NFe hardcoded, PDF, validação, métricas).
 - [Board-sync 2026-08-18](project_board-sync-2026-08-18.md) — 7 issues fechadas com evidência (#122,#33,#111,#113,#92,#93,#51); `Closes #N` na PR não garante fechamento automático, conferir sempre.
+- [Contrato linha vazia/progresso/degradação 2026-08-27](project_contrato-linha-vazia-progresso-degradacao-2026-08-27.md) — issues #194-#197; InformacoesParaEDI já resolvido em PR #191, não virou issue nova.

.claude/agent-memory/lp-pm/project_contrato-linha-vazia-progresso-degradacao-2026-08-27.md

@@ -0,0 +1,41 @@
+---
+name: project-contrato-linha-vazia-progresso-degradacao-2026-08-27
+description: Issues #194-#197 do doc de arquitetura contrato-linha-vazia-progresso-e-degradacao-posicional-2026-08-27; InformacoesParaEDI já resolvido em PR #191, sem issue nova.
+metadata:
+  type: project
+---
+
+Lote formalizado a partir de `docs/architecture/contrato-linha-vazia-progresso-e-degradacao-posicional-2026-08-27.md`
+(`@lp-architect`, 2026-08-27), que cobria 3 pedidos do dono + 1 achado já resolvido:
+
+- **#194** — story: `IsDeclaredEmpty` em `LineInfo`. Dono `lp-parser-llm`.
+- **#195** — story: fases discretas em `LowCodeTransformationIndexEntry.Status` (`uploaded`→`layout_selected`→`parsing`→`transforming`→`completed`/`partial`). Dono `lp-backend-dev`.
+  Complementa (não duplica) a **#99** (já existia — instrumentar/documentar o `transformationsTicket`
+  existente para o "trava em 100%"); #99 é sobre medição/documentação do que já existe, #195 é sobre
+  estender o enum de `Status` em si.
+- **#196** — bug: colapso posicional LINHA006 no `.mqseries` (todos os campos com
+  `startPosition===endPosition`). Dono `lp-parser-llm`, **bloqueado em `correlationId`** que só o
+  dono do projeto pode fornecer — severidade marcada "a validar" (sem confirmação de causa raiz
+  nem frequência em produção, só hipótese fundamentada em código).
+- **#197** — story: contrato aditivo `PositionalAlignmentFailed` por linha (sinal genérico de
+  degradação posicional, sem acoplar a `mapperName` — pedido explícito do dono). Relacionado a
+  #196 mas não depende do `correlationId` bloqueante daquela.
+
+**Achado importante nesta sessão:** o bug de `InformacoesParaEDI`/LINHA081 (Length=LengthField em
+fragmento bruto + falta de `OccurrenceCount`/`IsAggregatedOccurrence`), que o doc de arquitetura
+ainda descrevia como "não implementado", **já foi corrigido e mesclado** — commit `a330af2` na
+branch `fix/informacoesparaedi-length-e-occurrence-id`, PR **#191 (MERGED)**, validado por `@lp-qa`
+(PASS, 393/393 testes) conforme `.claude/agent-memory/lp-qa/informacoesparaedi-occurrencecount-fix-qa-gate.md`.
+Não havia issue prévia pra esse bug (nunca chegou a virar item de board), então **nenhuma issue foi
+criada** para ele — só registrado aqui como já resolvido. Reforça [[project-backlog-nao-e-prova-do-codigo]]:
+o doc de arquitetura (fonte da tarefa) estava desatualizado em relação ao código real; sempre
+verificar o estado atual antes de formalizar como pendência.
+
+Todas as 4 issues adicionadas ao Project #2 (Status=Todo). Field-ids confirmados iguais aos já
+registrados em [[reference-gh-cli-setup]] (Tipo: story=`b1173f83`, bug=`fb117f1c`; Dono:
+lp-parser-llm=`2cab763a`, lp-backend-dev=`c290c76b`).
+
+**Correção de referência:** `gh` neste ambiente (WSL/bash) está em `/usr/bin/gh` no PATH direto —
+o caminho absoluto Windows (`C:\Users\...\gh.exe`) documentado em [[reference-gh-cli-setup]] não
+existe neste shell. Atualizar a referência para citar ambos os caminhos possíveis conforme o
+ambiente (Windows/PowerShell vs. WSL/bash).

.claude/agent-memory/lp-pm/reference_gh_cli_setup.md

@@ -5,7 +5,7 @@ metadata:
   type: reference
 ---
 
-- `gh` CLI está em `C:\Users\elson.lopes\.local\bin\gh.exe` (caminho completo — não está no PATH). Usar sempre o caminho absoluto nas chamadas Bash.
+- `gh` CLI: no shell **PowerShell/Windows** está em `C:\Users\elson.lopes\.local\bin\gh.exe` (não está no PATH lá, usar caminho absoluto). No shell **WSL/bash** (ambiente mais comum destas sessões) `gh` já está no PATH direto (`/usr/bin/gh`, v2.45.0) — usar só `gh` sem prefixo de caminho. Confirmar o shell atual antes de assumir qual dos dois vale.
 - Repo alvo: `LayoutParser/LayoutParserApi`. Autenticado, com escopo `read:project` já concedido.
 - Checar duplicata antes de criar: `gh issue list --repo LayoutParser/LayoutParserApi --search "<termos>" --state all`.
 - Dono já autorizou criação direta de issues (sem rascunho prévio) quando a fonte é um diagnóstico técnico bem documentado (ex.: memória de outro agente `@lp-*`). Formato de corpo: `## Contexto` (com link pro arquivo de origem em `.claude/agent-memory/<agente>/`), `## O que falta`, `## Critério de aceite` (checklist), `## Dono natural`, `## Severidade` (ou `## Por que agora` para stories). Ver issues #30-#40 como padrão de capricho.

.claude/agent-memory/lp-qa/MEMORY.md

@@ -5,4 +5,6 @@
 - [Fine-tuning POC Fase 1 dataset QA](finetuning-poc-fase1-dataset-qa.md) — 39 pares filtrados (NFe 31/MDFe 6/CTe 2); 11/11 amostras OK; CTe com amostra fina (só 2); dataset OK p/ Fase 2 RAG.
 - [AI metrics Gap 3 QA gate](ai-metrics-gap3-qa-gate.md) — 6 bloqueios FECHADOS (9e48650) + hardening CONCERNS (e6df0b7); em aberto: duas pontes ativas contam cada geração 2x (54 vira 108, aprovação 100% vira 50%).
 - [Técnica: matriz de mutação](tecnica-matriz-de-mutacao.md) — julgue suíte reintroduzindo bugs numa cópia via `git archive` no scratchpad; nunca mutar a árvore compartilhada.
+- [InformacoesParaEDI OccurrenceCount fix QA gate](informacoesparaedi-occurrencecount-fix-qa-gate.md) — PASS a330af2 validado c/ amostra real; baseline 704 era stale, correto é 705 (pré-existente, não regressão).
 - [Cypress alpha emissão normal spec](cypress-alpha-emissao-normal-spec.md) — spec escrita em LayoutParserCypress; ambos pathways (TCL/XSL e LowCode) bloqueados no dev workstation por arquivos que só existem em `C:\inetpub\wwwroot\layoutparser\` de produção.
+- [PR #198 LineInfo signals QA gate](pr198-linhainfo-signals-qa-gate.md) — PASS; achado: IsDeclaredEmpty inalcançável na prática (matcher exige prefixo não-espaço); incidente de commits concorrentes no mesmo checkout.

.claude/agent-memory/lp-qa/informacoesparaedi-occurrencecount-fix-qa-gate.md

@@ -0,0 +1,30 @@
+---
+name: informacoesparaedi-occurrencecount-fix-qa-gate
+description: QA gate do fix Bug A (Length real) + OccurrenceCount/IsAggregatedOccurrence em ParsedField (commit a330af2) — PASS validado contra amostra real, não short-circuit
+metadata:
+  type: project
+---
+
+Fix de `InformacoesParaEDI`/LINHA081 (Lia, commit `a330af2`, worktree
+`agent-a08c990d4efceeb06`) validado com a amostra real (`.claude/tmp/26072026/`, copiada de
+`.claude/temp/teste/`) — os 4 testes de `PositionalFormatRegressionTests` rodaram de verdade
+(sem short-circuit) e passaram, mais suíte completa (382/382).
+
+**Achado durante a validação:** a contagem de baseline do MQSeries de controle estava errada em
+704 — o valor real e correto é **705**. Confirmado isolando a causa: rodei o mesmo teste contra o
+worktree PAI (950cdf9, commit anterior ao fix da Lia) com a mesma amostra real e ele também
+produzia 705, não 704. Ou seja, o "704" nunca tinha sido validado contra dado real (herdado de um
+período em que o teste sempre fazia short-circuit) — não é regressão introduzida pelo fix do Bug
+A/OccurrenceCount. Corrigi o assert para 705 e recapturei `MqBaselineSha256` =
+`453e9a184e253d1b310f7814282ebfddb9ca5a99f25acc65ecae741060c8ecfd` (script: adicionar
+temporariamente `File.WriteAllText` do hash completo, rodar, copiar valor, reverter o
+write temporário — `Assert.Equal` do xUnit trunca strings longas na mensagem de falha).
+
+**Why:** confiar apenas no assert de contagem sem isolar a causa (fix novo vs. comportamento
+pré-existente) teria devolvido um falso "achado" pra Lia corrigir algo que já estava certo.
+
+**How to apply:** ao validar hash/contagem baseline "STALE" documentado como pendente de
+recaptura, sempre isolar se o valor divergente é efeito do fix em revisão ou já preexistia —
+usar `git worktree add <commit-pai>` num scratchpad e rodar o mesmo teste contra a mesma amostra
+real é o jeito mais direto de provar isso. Ver também [[tecnica-matriz-de-mutacao]] para a mesma
+lógica de isolamento (copiar/rodar fora da árvore compartilhada).

.claude/agent-memory/lp-qa/pr198-linhainfo-signals-qa-gate.md

@@ -0,0 +1,59 @@
+---
+name: pr198-linhainfo-signals-qa-gate
+description: QA gate do PR #198 (IsDeclaredEmpty/PositionalAlignmentFailed/status "failed") — PASS com achado de design em IsDeclaredEmpty
+metadata:
+  type: project
+---
+
+PR #198 (`feat/contrato-linha-vazia-e-progresso` → `develop`), revisado em 2026-08-27.
+`dotnet build` limpo; `dotnet test` 385/389 (as 4 falhas são as pré-existentes de path
+Windows×Linux, ver [[unified-logging-parse-bug-and-log-dir-incident]] linha de raciocínio
+similar — não são regressão deste PR).
+
+**Achado de design (não é bug de implementação — o código bate com a spec):**
+`LineInfo.IsDeclaredEmpty` é calculado como `string.IsNullOrWhiteSpace(currentLine)` sobre a
+linha FÍSICA INTEIRA (Sequencia + InitialValue + campos), exatamente como o
+`docs/architecture/contrato-linha-vazia-progresso-e-degradacao-posicional-2026-08-27.md` §1
+especifica. Só que todo matcher em `IsLineValidForConfig` (`Services/Implementations/
+LayoutParserService .cs`) exige um prefixo NÃO-espaço pra casar a linha com uma config de layout
+(sequência numérica de 6 dígitos, `HEADER`, `EDI_`/`ZRSDM_`, ou `999999`) — então uma linha
+"identificada" (`matchingLineConfig != null`) NUNCA pode ser 100% whitespace, e uma linha 100%
+whitespace nunca é identificada (cai em `unidentifiedLines`, `lineInfos` fica vazio pra ela).
+Resultado: `IsDeclaredEmpty=true` é, na prática, inalcançável para MQSeries/IDOC — mesmo quando
+o CAMPO de dado real está 100% em branco, porque o Sequencia/InitialValue não-espaço no início
+da linha já derruba o `IsNullOrWhiteSpace`. Confirmado com 2 testes que reproduzem exatamente
+esse cenário em `tests/LayoutParserApi.Tests/Parsing/LineInfoAdditiveSignalsTests.cs`
+(`ACHADO_dado_totalmente_em_branco_no_campo_nao_liga_IsDeclaredEmpty` e
+`ACHADO_linha_totalmente_em_branco_nao_gera_LineInfo_nenhum`).
+
+**Why:** se a intenção de produto é "avisar quando o DADO da linha está vazio" (uso plausível:
+o front sinalizar ao usuário que uma linha declarada no layout veio sem conteúdo), o sinal como
+implementado não entrega isso — ele só dispara pra um cenário que as regras de matching atuais
+tornam impossível. Vale a pena `@lp-architect`/`@lp-parser-llm` revisitarem se o cálculo deveria
+comparar o(s) campo(s) de DADO (não-Sequencia/InitialValue) em vez da linha bruta inteira.
+
+**How to apply:** ao revisar qualquer sinal aditivo que dependa de "linha bruta" vs. "campo
+extraído", extrair um caso de teste síntetico ANTES de aprovar — spec e código podem concordar
+entre si e ainda assim não produzirem o comportamento que o produto quer. Não é suficiente
+verificar "código bate com spec"; é preciso perguntar se a spec cobre os matchers já existentes.
+
+**Cobertura de teste adicionada nesta sessão** (5 testes de linha + 2 de status "failed" no
+índice low-code): `tests/LayoutParserApi.Tests/Parsing/LineInfoAdditiveSignalsTests.cs` (novo
+arquivo) e 2 métodos em `tests/LayoutParserApi.Tests/Transformation/
+LowCodeTransformationStoreTests.cs`. `PositionalAlignmentFailed` tem reprodução sintética via
+dois `FieldElement` com `LengthField=0` consecutivos (mesmo `Start`) — não depende do
+correlationId pendente do caso real LINHA006.
+
+**Incidente de processo (não é bug de produto):** durante esta sessão, dois agentes concorrentes
+(backend-dev corrigindo `Controllers/ParseController.cs` para expor `LineInfos` no payload de
+Upload, e outro fechando a spec doc) rodaram commit no MESMO checkout de working directory
+(sem worktree isolado para esta branch), e absorveram sem querer meus arquivos de teste
+untracked/modificados nos commits deles (`3ffe2ec`/`abea2b5`) via `git add`/`commit -a` amplo.
+Nada foi perdido — o conteúdo está correto na árvore — mas as mensagens de commit não mencionam
+os testes de QA que vieram junto. Nenhum push aconteceu ainda (branch local `ahead 2` do
+`origin`), então dá pra reescrever a atribuição antes do push se `@lp-devops` achar que vale a
+pena; senão, é só ruído de changelog.
+
+**Veredito: PASS.** Build limpo, testes verdes (incluindo os 7 novos), gaps de cobertura
+fechados. O achado de `IsDeclaredEmpty` é recomendação de follow-up, não bloqueador — o contrato
+aditivo não quebra nada existente, só entrega menos valor de sinal do que a spec pretendia.

Controllers/ParseController.cs

@@ -253,7 +253,17 @@ public async Task<IActionResult> Upload(IFormFile layoutFile, IFormFile txtFile,
                             var autoResult = await transformTask;
                             syncCts.Dispose();
 
-                            transformationsStatus = autoResult.Applicable ? "completed" : "not_applicable";
+                            // ✅ "failed" (contrato aditivo 2026-08-27, spec §2): existe candidato mas
+                            // NENHUM teve sucesso — distinto de "completed" (ao menos um candidato OK),
+                            // sem exigir que o front varra o array pra descobrir que deu tudo errado.
+                            var todosFalharam = autoResult.Applicable
+                                && autoResult.Candidates.Count > 0
+                                && autoResult.Candidates.All(c => !c.Success);
+
+                            transformationsStatus = !autoResult.Applicable
+                                ? "not_applicable"
+                                : todosFalharam ? "failed" : "completed";
+
                             if (autoResult.Applicable)
                             {
                                 transformations = AplicarTetoDeXmlInline(autoResult.Candidates);
@@ -303,10 +313,11 @@ public async Task<IActionResult> Upload(IFormFile layoutFile, IFormFile txtFile,
                     summary = result.Summary,
                     documentStructure = documentStructure,
                     lineValidations = lineValidations, // Validações e posições calculadas (apenas para layouts configurados)
+                    lineInfos = result.LineInfos, // ✅ Contrato aditivo 2026-08-27: sinais por linha (IsDeclaredEmpty, PositionalAlignmentFailed)
                     validationErrors = result.ValidationErrors, // ✅ Erros de validação de tamanho de linha
                     validationWarning = !string.IsNullOrEmpty(result.ErrorMessage) ? result.ErrorMessage : null, // ✅ Aviso se houver erros
                     transformations, // array de candidatos low-code (mapper/target/xml/sucesso-ou-erro) quando concluído a tempo
-                    transformationsStatus, // "not_applicable" | "completed" | "processing" | "error"
+                    transformationsStatus, // "not_applicable" | "completed" | "failed" | "processing" | "error" (contrato aditivo 2026-08-27: "failed" é novo — ver GetTransformations)
                     transformationsReason, // opcional: no_mapper | type_not_positional | empty_input | timeout_sync | structural_error
                     transformationsTicket // consulta do resultado: GET /api/parse/transformations/{ticket}
                 });
@@ -339,9 +350,22 @@ public async Task<IActionResult> Upload(IFormFile layoutFile, IFormFile txtFile,
         /// consome, para não criar um terceiro dialeto (spec §3.3).</para>
         /// </summary>
         /// <param name="ticket">"{sha256}.{layoutGuid}" — devolvido pelo upload em <c>transformationsTicket</c>.</param>
-        /// <response code="200">Manifesto encontrado (status "processing" ou "completed").</response>
+        /// <response code="200">Manifesto encontrado (status "processing" | "completed" | "failed").</response>
         /// <response code="400">Ticket fora do formato.</response>
         /// <response code="404">Nenhuma execução registrada para este ticket.</response>
+        /// <remarks>
+        /// Contrato aditivo (2026-08-27, ver
+        /// <c>docs/architecture/contrato-linha-vazia-progresso-e-degradacao-posicional-2026-08-27.md</c>
+        /// §2): o vocabulário completo de fases é <c>"uploaded"</c> → <c>"layout_selected"</c> →
+        /// <c>"parsing"</c> → <c>"transforming"</c> → <c>"completed"</c>/<c>"failed"</c>, mas as 3
+        /// primeiras são <b>client-side only</b> — este endpoint só existe (índice só é gravado) a
+        /// partir de depois que o documento já foi parseado, então a API nunca as emite. O que
+        /// este endpoint efetivamente retorna em <c>status</c> é <c>"processing"</c> (valor de fio
+        /// inalterado — equivale à fase "transforming"), <c>"completed"</c> (≥1 candidato com
+        /// sucesso) ou <c>"failed"</c> (novo: existe candidato, mas nenhum teve sucesso — antes
+        /// isso vinha como "completed" com <c>success=false</c> em todos os itens de
+        /// <c>candidates</c>, obrigando o front a inferir o fracasso varrendo o array).
+        /// </remarks>
         [HttpGet("transformations/{ticket}")]
         public async Task<IActionResult> GetTransformations(string ticket)
         {
@@ -359,7 +383,7 @@ public async Task<IActionResult> GetTransformations(string ticket)
             {
                 success = true,
                 ticket,
-                status = entrada.Status, // "processing" | "completed"
+                status = entrada.Status, // "processing" | "completed" | "failed" (contrato aditivo 2026-08-27)
                 partial = entrada.Partial, // true = execução interrompida no teto síncrono; pode faltar candidato
                 candidates = entrada.Candidates.Select(c => new
                 {

Models/Entities/LineInfo.cs

@@ -8,5 +8,19 @@ public class LineInfo
         public int StartPosition { get; set; }
         public int Length { get; set; }
         public string Content { get; set; } = string.Empty;
+
+        /// <summary>
+        /// Aditivo: true quando a linha foi identificada no layout (matchingLineConfig != null)
+        /// mas o conteúdo bruto da linha é vazio/whitespace. Ortogonal ao Status por campo —
+        /// não substitui nem altera nenhuma sinalização existente.
+        /// </summary>
+        public bool IsDeclaredEmpty { get; set; }
+
+        /// <summary>
+        /// Aditivo: true quando ≥2 campos consecutivos desta ocorrência de linha resolveram para
+        /// a mesma posição inicial (fieldStart colapsado) — sintoma observável de degradação
+        /// posicional (ex.: LINHA006), não a causa raiz nem o mapeador de origem.
+        /// </summary>
+        public bool PositionalAlignmentFailed { get; set; }
     }
 }