CommitLore

CommitLore

Pare de revisar a mesma má ideia repetidamente.

Autoridade de decisão para agentes de codificação, controlada pelo Git.
Mantenha restrições, alternativas rejeitadas e avisos no Git — e entregue apenas o que ainda está em vigor, para que um agente não receba uma decisão que o repositório já reverteu.

Sem memória hospedada. O repositório é o dono do registro.

English · 한국어 · 日本語 · 简体中文

Instale uma vez. Depois inicialize cada repositório onde você quiser que funcione.

curl -fsSL https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.sh | sh -s v1.2.0

curl -fsSLO https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.sh
sh install.sh v1.2.0

# Or skip the script: the checkout it makes is one you can make yourself.
git clone --depth 1 --branch v1.2.0 https://github.com/MongLong0214/commitlore
node commitlore/dist/commitlore.mjs --version

O código sobrevive. O julgamento não.

Um agente propõe uma abordagem. Sua equipe a rejeita por causa de uma restrição não óbvia. O código final preserva o resultado, mas geralmente não o motivo pelo qual a alternativa foi rejeitada. Um agente posterior vê apenas o código e propõe a mesma ideia novamente.

CommitLore mantém esse julgamento ao lado do código.

O que o CommitLore faz

A maioria dos commits não deve carregar registro. CommitLore é para julgamento que o código não consegue preservar, não para narrar cada mudança.

60 segundos para agentes cientes de decisões

1. Instale a CLI

macOS e Linux:

curl -fsSL https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.sh | sh -s v1.2.0

Windows:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.ps1))) v1.2.0

Requer Node.js 22.23.2+ e Git. O script verifica ambos antes de escrever qualquer coisa.

2. Conecte seu agente

Claude Code:

/plugin marketplace add MongLong0214/commitlore
/plugin install commitlore@commitlore

Codex:

commitlore plugin install-codex

O plugin não coloca commitlore em PATH, então os comandos abaixo precisam da instalação da CLI também. Os instaladores também detectam e conectam hosts MCP suportados onde podem fazer isso com segurança; a matriz exata está abaixo.

3. Inicialize um repositório

cd your-repository
commitlore init
commitlore context .

Inicie uma nova sessão de agente após instalar ou atualizar um plugin: uma sessão em execução mantém o runtime que carregou.

Depois, trabalhe e faça commits normalmente. Em integrações de skill suportadas, o CommitLore é considerado durante solicitações de commit comuns e permanece silencioso quando não há nada que valha a pena preservar. Você não precisa nomear o CommitLore em todo commit.

Quer que registros aceitos sejam preparados sem um prompt por registro? O repositório pode optar por isso uma vez com commitlore auto on. Essa política é de propriedade do repositório e se aplica à equipe, então não é habilitada silenciosamente por esta página.

O que o agente recebe

Antes de editar src/pricing.ts:

commitlore: active records for src/pricing.ts

Limit
  [claim] r-price01  calculatePrice owns final checkout pricing only

Ruled-out
  [claim] r-price01  Reuse it for admin quotes |
                     eligibility and rounding semantics differ

[claim] significa "considere isso como informação." Um repositório pode optar pelo modo mais forte de autoridade assinada. A entrega dá contexto ao agente; ela não bloqueia a edição.

Modelo de segurança →

Por que Git?

O repositório deve ser dono do julgamento por trás do seu código.

CommitLore armazena registros em trailers e notas comuns do Git, então eles fazem branch, merge, clone, revisão e sobrevivem a mudanças de provedor junto com o código que explicam.

SQLite é apenas um índice reconstruível. Apague-o e o Git ainda mantém o registro.

Encontrar uma decisão antiga não é suficiente

Um sistema geral de memória ou recuperação pergunta:

Qual texto antigo parece relacionado?

CommitLore pergunta:

Quais decisões registradas ainda se aplicam a este caminho agora?

Uma decisão substituída pode ser altamente relevante e ainda assim estar errada como orientação atual. Relevância e autoridade são perguntas diferentes.

Como funciona

1. Captura — um agente redige apenas o contexto de decisão que o diff não consegue mostrar.
2. Verifica — CommitLore confere o rascunho contra a sessão e o diff preparado.
3. Preserva — o registro aceito vive no Git com identidade e ciclo de vida.
4. Entrega — antes de uma edição posterior, apenas registros ativos para aquele caminho são retornados.

A maioria dos commits não carrega registro. O hook de commit valida um registro quando um está presente; ele não inventa um.

Um hook existente não é sobrescrito. commitlore init honra core.hooksPath, move qualquer hook já instalado para <hook>.commitlore-chained e o chama primeiro; commitlore hooks uninstall o coloca de volta.

O que acontece automaticamente

"Disponível" significa que o fluxo de preparar → verificar → preparar existe. Não significa que todo commit elegível é avaliado automaticamente.

Usuários em hosts de skill suportados não precisam dizer "registre isso no CommitLore" em todo commit. A limitação restante é a iniciação do host, não um comando de usuário obrigatório por registro.

Um relato de campo, não uma medição

Uma execução, em um repositório não relacionado, por alguém instalando v1.2.0 pela primeira vez. Nada aqui foi medido e nada disso está nos logs de evidência. Está nesta página porque o parágrafo acima afirma um loop que nenhuma tabela aqui cobre.

Eles pediram a um agente para corrigir um bug de arredondamento, mencionaram de passagem que uma biblioteca decimal já havia sido considerada e descartada, e terminaram com "faça o commit". CommitLore nunca foi nomeado. Parte do que o commit carregou:

Ruled-out: adopting a decimal library such as Decimal.js | the backend is a
  number contract, so it is meaningless
Warn: do not revert the test file to console.assert: it exits 0 even on
  failure, so CI passes silently
Provenance: drafted

O Warn não foi ditado ao agente. Ele caiu na armadilha enquanto trabalhava e deixou para quem viesse depois. Provenance: drafted registra que nenhum humano leu o registro, o que o classifica como claim — entregue como um relatório para considerar, não uma ordem.

Uma sessão posterior sem histórico compartilhado foi solicitada a adotar a biblioteca decimal afinal. Ela não adotou e citou o registro como motivo. Também leu a classificação: um claim não é uma instrução, então verificou o motivo declarado contra o código antes de concordar com ele.

Diferente de armazenamento de memória

CommitLore é intencionalmente mais estreito. Não é um sistema de memória de usuário geral, arquivo de conversa ou substituto de banco vetorial.

Evidência

O tempo de construção do índice segue o número de registros, não o número de commits: a passagem cara roda uma vez por registro, então um histórico longo com pouco registrado constrói mais rápido do que um curto e denso em registros.

O escopo de caminho é o que impede um histórico grande de chegar ao modelo. No corpus #167, apenas 2 de 10.002 registros chegaram:

Isso mede exposição e recall em um orçamento fixo de dois registros — não custo de token, custo cobrado, precisão ou comportamento do agente. Um corpus, uma consulta, um modelo de embedding fixado.

O estudo de agente não estabelece um efeito universal de modelo. A entrega não é prova de que um modelo leu ou seguiu um registro.

Métodos, tabelas completas, exclusões e resultados negativos →

Limites, confiança e privacidade

• A captura é assistida, não determinística. As habilidades suportadas consideram solicitações de commit comuns, mas nenhum host é certificado para avaliar todos os commits elegíveis.
• O modo de diretiva padrão não é autenticação. Ele corresponde ao cabeçalho do autor do commit, e qualquer pessoa que possa escrever um commit pode definir esse cabeçalho — portanto, um [directive] no modo padrão é metadados de política, não prova de identidade. O modo de assinatura adicionalmente exige o status verificado do próprio Git e uma correspondência na lista de permissões commitlore.trustedSigner local do repositório; uma lista de permissões de signatários ausente, vazia ou ilegível não autoriza ninguém, então o modo falha de forma segura.
• O guard é um aviso experimental, não uma rede de segurança: precisão 44,8% (IC de Wilson de 95%: 32,7%–57,5%), recall 22,0% no corpus de 417 decisões. Um resultado de guard vazio não é um veredito de segurança.
• A entrega gasta tokens em cada chamada de ferramenta correspondente. O hook de pré-edição dispara em Read bem como em Edit, Write, MultiEdit e NotebookEdit, então ele roda com muito mais frequência do que um agente de edição faz commits. Cada disparo gasta até o orçamento de payload — 800 tokens por padrão, alterado com --budget. Um repositório sem registros não gasta nada, o que significa que este é um custo que chega com a adoção, não com a instalação.
• Uma resposta pode ser parcial. A cobertura é divulgada; a ausência em um resultado parcial não é prova de que nenhum registro existe. Cobertura em todo o repositório, âncoras de símbolos e um construtor interativo de registros permanecem em aberto: #32, #33.
• Os trailers de commit viajam com um clone; as notas não. O Git não busca refs/notes/* por padrão, então um registro em refs/notes/commitlore está ausente de um clone comum até que commitlore init configure esse espelho.
• Não há backend hospedado. Mas uma vez que o servidor ou hook retorna contexto, o host lida com esse contexto sob sua própria política; o CommitLore não controla esse fluxo de dados.

Segurança · Compatibilidade · Evidências

Experimente em um repositório com histórico.
_{Diga-nos onde o escopo de caminho, ciclo de vida, captura ou instalação falha.}

Relate um caso de falha · Leia a auto-auditoria

Documentação

• Instalar, atualizar e desinstalar
• Referência CLI
• Fluxo de captura
• Protocolo de registro
• Modelo de segurança
• Evidências e limitações
• Contrato de produção
• Índice de documentação

Contribuindo

CONTRIBUTING.md cobre o protocolo de registro ao qual este repositório se compromete, o portão de lançamento e como reproduzir as evidências.

Licença

MIT — veja LICENSE.