fill CLI remove frontmatter YAML de docs/agents e listToFill não verifica status

[contato121]

Descrição

O comando fill remove o frontmatter YAML dos arquivos de docs/ e agents/ após preencher o conteúdo, e o listToFill (MCP) não verifica o campo status — lista todos os arquivos incondicionalmente. Isso cria um loop destrutivo onde o usuário/agente sempre acha que precisa rodar fill novamente, sobrescrevendo conteúdo já preenchido.

Versão

@ai-coders/context@0.7.0

Passos para Reproduzir

# 1. Init limpo
npx @ai-coders/context@latest init . both -v

# 2. Verificar que frontmatter foi criado corretamente
head -5 .context/docs/architecture.md
# Output:
# ---
# type: doc
# name: architecture
# description: System architecture...
# category: architecture

# 3. Fill com provider Google
export GOOGLE_API_KEY="..."
npx @ai-coders/context@latest fill . -v --provider google

# 4. Verificar frontmatter após fill
head -5 .context/docs/architecture.md
# Output:
# # Architecture Notes          ← FRONTMATTER FOI REMOVIDO
#
# The OABot system is designed...

# 5. Verificar status nos agents
grep "^status:" .context/agents/*.md
# Resultado: apenas 5 de 14 agents têm status, e o valor é "active" (não "filled")

# 6. Via MCP, listToFill reporta TODOS como pendentes
# (sempre retorna 23 arquivos independente do status)

Comportamento Esperado

1. Após fill, docs e agents deveriam manter frontmatter com status: filled
2. listToFill deveria filtrar arquivos que já têm status: filled
3. Re-executar fill não deveria sobrescrever conteúdo já preenchido

Comportamento Atual

1. fill remove o frontmatter via removeFrontMatter() em fillService.js:processTarget()
2. listToFill lista todos os .md sem verificar status (em fillScaffoldingTool.js)
3. collectTargets() processa todos os arquivos sem filtrar por needsFill()
4. Agents recebem status: active (quando o LLM gera frontmatter) em vez de status: filled

Análise do Source Code

1. fillService.js — processTarget() (~linha 150)

// Remove front matter from filled content (status: unfilled marker)
const cleanContent = removeFrontMatter(updatedContent);
await fs.writeFile(target.fullPath, this.ensureTrailingNewline(cleanContent));

O frontmatter é intencionalmente removido. Mas isso significa que docs/agents perdem todo o metadata.

2. fillScaffoldingTool.js — listFilesToFillTool

const docFiles = await fs.readdir(docsDir);
for (const file of docFiles) {
    if (!file.endsWith('.md')) continue;
    files.push({ path, relativePath, type: 'doc' });
}

Lista TODOS os .md sem nenhuma verificação de status.

3. frontMatter.js — needsFill()

async function needsFill(filePath) {
    const firstLines = await readFirstLines(filePath, 3);
    return firstLines.some(line => line.includes('status: unfilled'));
}

Só lê as 3 primeiras linhas, mas status: está na linha ~8 do frontmatter. Nunca detectaria.

Impacto

• Perda silenciosa de dados: cada re-fill sobrescreve conteúdo editado manualmente
• Loop infinito: listToFill sempre reporta pendências → agente roda fill → conteúdo regenerado → repete
• Inconsistência: skills recebem status: filled corretamente, mas docs/agents não

Sugestão de Correção

1. processTarget(): após fill, adicionar frontmatter com status: filled via addFrontMatter() em vez de chamar removeFrontMatter()
2. listFilesToFillTool: filtrar usando needsFill() antes de incluir no resultado
3. collectTargets(): filtrar por needsFill() para evitar re-fill destrutivo
4. needsFill(): ler linhas suficientes (10+) para encontrar o campo status

Ambiente

• OS: Windows 11
• Node: v20.x
• @ai-coders/context: 0.7.0
• Provider testado: Google (gemini-3-flash-preview)
• Reproduzido tanto via CLI quanto via MCP (Claude Code)

[LorranHippolyte]

Olá! Vou trabalhar nessa issue e abrir um PR em breve com o fix.