Gerenciador de Inventário de Ativos

O que Gerenciador de Inventário de Ativos faz?

Mantenha uma Lista de Ativos autoritativa e auditável por projeto. Os dados residem na pasta .asset-inventory/ do próprio projeto (um arquivo JSON por ativo) e uma visão Markdown gerada (padrão ASSET_LIST.md). Nunca edite a visão Markdown manualmente: altere os registros com a CLI, que a regenera.

A CLI

Todas as operações passam por um único script Python 3.9+ (stdlib) nesta skill:

python <diretório-da-skill>/scripts/asset_inventory.py <comando> [opções]

Abaixo, aim representa esse comando. Se python estiver ausente ou não for Python 3, tente python3, depois py -3 (Windows), depois uv run --no-project python. Execute de qualquer lugar dentro do projeto, ou passe -C <projeto>. Adicione --json para saída legível por máquina. O histórico registra o agente atuante: passe --agent <nome> ou defina AIM_AGENT quando a detecção automática estiver incorreta.

Tarefa	Comando
Iniciar um inventário	aim init --profile game|vr|web|software|generic [--git-setup]
Registrar um ativo	aim add --name "Arco" --category model --path assets/bow.glb --origin third-party --license CC-BY-4.0 --source-url URL --attribution required --credit "..."
Alterar um ativo	aim update ID --status final --verification approved --note "motivo"
Aposentar / excluir	aim remove ID --note "substituído por X" (mantém o registro) / --purge
Encontrar ativos	aim query --category model --status placeholder, --path assets/ui/, --text arco, --format json|csv|ids
Um registro	aim get ID
Encontrar arquivos não registrados	aim scan (adicione --register para criar registros de triagem)
Verificar tudo	aim audit (--strict faz avisos falharem)
Reconstruir o Markdown	aim render (--check para CI)
Contexto (branch, worktree, trava)	aim info
Migrar uma tabela Markdown antiga	aim import-markdown lista_antiga.md
Após um conflito Git	aim resolve, depois aim audit

Vocabulário (veja esquema para todos os campos):

• status: planned, placeholder (funciona, qualidade de protótipo), integrated, final, retired.
• verification: unverified, pending, verified (verificações técnicas aprovadas), approved (aprovado pelo proprietário). Nunca marque como approved a menos que o usuário ou revisor tenha aprovado.
• origin: original, third-party, procedural, ai-generated, unknown. Ativos de terceiros e gerados por IA exigem uma licença.

Fluxo de trabalho

1. Localize. Execute aim info. Se não existir inventário e o usuário quiser um, execute aim init com o perfil mais próximo (perfis), depois aim scan para ver o que já existe. Para uma lista manuscrita existente, use aim import-markdown e revise os registros marcados como imported.
2. Registre cada alteração de ativo no mesmo conjunto de alterações. Ao adicionar, substituir, modificar, mover ou excluir um arquivo de ativo, atualize seu registro no mesmo commit: add para novos arquivos, update --add-path/--remove-path para movimentos, update --modifications para edições em arquivos de terceiros, remove quando não utilizado.
3. Registre a proveniência honestamente. Capture a URL de origem real, autor, licença e texto de crédito exigido no momento do download. Se desconhecido, use --origin unknown e informe; nunca adivinhe uma licença. Sinalize conflitos de licença ao usuário.
4. Mantenha os estados verdadeiros. Diferencie planejado, implementado, verificado e aprovado. Coloque a próxima verificação pendente em --next; ela aparece em "Needs review" no topo da lista.
5. Audite antes de finalizar. Execute aim audit. Corrija erros; relate avisos restantes ao usuário. Mencione o caminho da lista em seu resumo.

Regras de colaboração (vários agentes, branches, worktrees)

Detalhes: colaboração.

• Cada Git worktree tem sua própria cópia do inventário; edite o que está no worktree em que você está trabalhando. Nunca edite o worktree de outro agente.
• Gravações usam uma trava curta (.asset-inventory/.lock), portanto agentes compartilhando uma pasta não podem corromper arquivos. Se uma trava for reportada, aguarde e tente novamente; exclua-a apenas se aim info mostrar que o processo proprietário não existe mais.
• Para evitar perda de atualizações, leia com aim get ID, depois aim update ID --expect-revision N. Código de saída 3 significa que outra pessoa o alterou: releia e reaplique.
• Um arquivo por ativo significa que branches paralelas raramente entram em conflito. Execute aim git-setup uma vez por clone para instalar o driver de merge de nível de campo.
• Após qualquer merge, rebase ou cherry-pick: aim resolve (se os registros mostrarem marcadores de conflito ou _conflicts), depois aim render, depois aim audit, depois commit. Nunca mergeie manualmente ASSET_LIST.md; regenerue-o.
• IDs explícitos como M01 são aceitáveis em um branch; IDs padrão (<prefixo>-<slug-do-nome>) evitam colisões de numeração entre branches.

Códigos de saída

0 ok · 1 erro ou auditoria falhou · 2 uso incorreto/valor desconhecido · 3 revisão ou conflito de merge necessitando atenção.