Faça pequenas mudanças em um app que roda sobre um serviço local em segundo plano (daemon)

## Antes de programar, leia os documentos de projeto e entenda o papel de cada pasta Mantenha as alterações pequenas, siga a arquitetura que o repositório busca atualmente e prefira as fronteiras documentadas de daemon/API em vez do comportamento herdado de uma implementação mais antiga que está sendo substituída. Aprenda a organização por função, não por nome de arquivo: - O backend contém o cliente de linha de comando, o daemon HTTP de loopback, os serviços, o armazenamento em banco de dados embutido, a lógica de ciclo de vida/reaper, os adaptadores de runtime e de workspace, e seus testes. - O front-end desktop ou web é um supervisor leve e uma superfície de UI conectada ao daemon por meio de um cliente tipado gerado. Não mova lógica do daemon para dentro dele. - O diretório de documentação contém as notas atuais de arquitetura e de status. Leia-as antes de alterar o comportamento de ciclo de vida, do cliente, do agente, do armazenamento ou do daemon. - Um diretório de testes separado contém os recursos externos de smoke test e de ponta a ponta, incluindo verificações em contêiner de instalação limpa. - As definições de workflow de CI são a referência do que precisa passar. Espelhe esses comandos localmente quando possível. Leia nesta ordem antes de uma alteração não trivial: o README de início rápido, o índice da documentação, o documento de arquitetura (modelo mental, organização dos pacotes, fronteiras de ciclo de vida/sessão/serviço e regras estruturais), o documento de status (o que já está entregue na branch principal hoje versus o que ainda está em andamento) e o documento do cliente (o formato pretendido dele). Se o repositório também mantiver arquivos-ponteiro de compatibilidade para outras ferramentas de agente, trate-os como redirecionamentos para o único guia canônico, e não como conjuntos de regras separados. Localize os pontos de entrada por responsabilidade, em vez de pesquisar às cegas: implementações de comandos, controladores HTTP e DTOs, fronteiras de leitura/escrita dos serviços, vocabulário de domínio, contratos de portas, consultas e migrações de banco de dados, e código de banco de dados gerado — cada um vive em seu próprio pacote. Siga os padrões de comando e de teste vizinhos antes de introduzir um novo estilo. ## Rode as verificações do projeto e veja na tela as mudanças visuais Use os comandos agregados do próprio repositório em vez de inventar comandos improvisados. A partir da raiz do repositório, eles normalmente cobrem: lint (testes do backend mais uma versão fixada do linter), verificação de tipos do front-end, regeneração do código de acesso ao banco de dados a partir das consultas e do schema, regeneração da especificação da API e dos tipos do front-end, e um executor local de workflows que valida as definições de CI (o que pode exigir um socket de contêiner). As verificações em nível de componente ainda valem a pena ser executadas diretamente durante a iteração: build, teste, teste com detecção de disputa (race) habilitada, análise estática (vet) e inicialização do serviço para o backend; verificação de tipos e build para o front-end. Quando uma alteração for visível na UI, renderize-a de fato dentro da sessão usando o comando de pré-visualização do projeto e observe o resultado. Não se limite a descrever como a alteração deveria ficar. ## Indique o app de desktop com atualização automática como única forma de instalar Quando um projeto tem mais de um caminho de instalação, apenas um é canônico, e as orientações precisam apontar para ele. - O build de desktop com atualização automática publicado por meio dos releases é o caminho de instalação canônico. Direcione os usuários para ele primeiro. - Um canal legado de gerenciador de pacotes pode continuar funcionando mesmo sem ser mais recomendado. Se uma versão final já foi publicada e o pacote está congelado, ele não recebe mais atualizações. Ele permanece como porta de entrada apenas para usuários que já têm o comando no PATH, caso em que executá-lo baixa e abre o build canônico. - Não adicione funcionalidades, documentação ou fluxos que tratem um canal legado congelado como a forma pretendida de instalar o produto. ## Mude só o que a tarefa pede e siga a divisão atual do código - Mantenha cada alteração diretamente ligada à tarefa. Evite limpezas oportunistas, renomeações amplas, mudanças de formatação sem necessidade, abstrações especulativas e refatorações arquiteturais, a menos que a tarefa peça explicitamente por elas. - Siga as fronteiras de pacote existentes. O código do cliente chama as rotas HTTP do daemon por meio dos utilitários de cliente compartilhados; ele não pode abrir o banco de dados, iniciar runtimes nem chamar adaptadores diretamente. - Mantenha cada comando em seu arquivo de comando correspondente e faça testes em tabela para ele no estilo dos testes de comando vizinhos. - Espelhe os DTOs de requisição e de resposta no lado do cliente, em vez de importar pacotes de controlador do servidor para dentro do código do cliente, a menos que essa dependência já esteja estabelecida no pacote. - Retorne erros de uso por meio do tipo dedicado de erro de uso, para que o uso incorreto do cliente saia com seu próprio código de status (por exemplo, 2), enquanto falhas de runtime e do daemon saem com o código de falha geral (por exemplo, 1). - Preserve os envelopes de erro da API e os IDs de requisição ao expor erros do daemon, em vez de achatá-los em strings simples. - Passe um contexto de cancelamento/prazo como primeiro argumento de qualquer função que realize I/O ou trabalho bloqueante. - Não adicione abstrações para casos de uso pontuais. Introduza um utilitário apenas quando ele eliminar duplicação entre pontos de chamada reais. - Os testes devem cobrir o comportamento visível para o usuário e a fronteira que está sendo alterada: o caminho feliz, a validação e os argumentos ausentes, os envelopes de erro do daemon e qualquer caminho de confirmação destrutiva. ## Não mude nem acrescente acessos de rede ao daemon - O listener primário do daemon permanece vinculado ao endereço de loopback e permanece sem autenticação. Não altere o host de vinculação dele e não adicione autenticação a ele. - O daemon pode executar um segundo listener, de adesão explícita, que vincula todas as interfaces para acesso pela rede local, mas somente enquanto estiver explicitamente habilitado, somente atrás do middleware de autenticação por senha bearer e servindo somente a API da aplicação. Esse listener nunca deve servir as rotas de controle restritas ao loopback, como desligamento, telemetria e controle remoto. - Onde esse listener é em texto puro e destinado apenas a uma rede doméstica confiável, isso é uma decisão deliberada e documentada, registrada em um registro de decisão de arquitetura. Leia esse registro antes de mexer nele. - Não adicione nenhuma outra vinculação exposta à rede. - O cliente de linha de comando permanece um cliente leve. Não porte comportamentos antigos em processo que contornem as rotas HTTP do daemon. ## Proteja os dados salvos e não edite à mão o código de banco de dados gerado - Não armazene status derivado ou voltado à exibição. Derive o status a partir de fatos duráveis (estado de atividade, flag de encerramento, fatos de pull request/verificação/comentário) no momento da leitura pelo serviço. - Não trate uma sondagem de runtime falha ou desconhecida como prova de que uma sessão está morta. - Não force a exclusão de worktrees registradas que ainda tenham alterações não commitadas. - Não modifique migrações que já foram mescladas. Em vez disso, adicione uma nova migração. - Não edite manualmente o código de banco de dados gerado. Altere as consultas ou as migrações e execute o gerador novamente. - Os eventos de alteração fluem dos triggers do banco de dados para o log de alterações. Não adicione um caminho paralelo e manual de emissão de alterações a partir dos métodos do store, a menos que a arquitetura mude explicitamente. - Fique atento a divergências entre os artefatos de API gerados e os DTOs escritos à mão. Os formatos de resposta dos controladores ficam em um único arquivo de DTO, e os testes podem verificar a compatibilidade de protocolo entre as camadas de cliente e HTTP. - Não adicione chamadas de rede aos testes, a menos que o pacote já tenha um padrão de integração ou de ponta a ponta para elas. Prefira servidores de teste em processo, fakes e dependências injetadas. - Não faça commit de estado local de execução, dados do daemon, worktrees temporárias, saídas de build ou credenciais. - Mantenha todo o estado da aplicação sob o único diretório de estado dedicado, que pode ser sobrescrito por meio das variáveis de ambiente documentadas. O diretório de dados do daemon, o arquivo de processo em execução, as worktrees e os dados de usuário do shell desktop (cache do navegador, cookies, armazenamento local e de sessão, despejos de falha) devem todos ser resolvidos dentro dele. Nunca leia nem escreva no local padrão de dados de aplicação do sistema operacional. O ponto de entrada do desktop fixa o caminho de dados de usuário do shell nesse diretório; não remova essa sobrescrita nem dependa do caminho padrão. ## Mude a API nos arquivos escritos à mão e gere de novo a descrição dela A API do daemon é code-first. A especificação OpenAPI e os tipos do front-end são artefatos gerados, portanto edite a origem e regenere, em vez de editar as saídas. - Edite o arquivo de DTO que define os formatos de requisição e de resposta. - Edite o registro de operações do construtor de especificação, adicionando uma entrada de nome de schema para qualquer tipo recém-nomeado. - Regenere com o comando agregado de API do repositório, que executa a geração da especificação e a geração de tipos em sequência. - Verifique com os testes do pacote HTTP do servidor; eles cobrem divergência de especificação e paridade entre rotas e especificação. Eles não cobrem os tipos gerados do front-end, que são verificados por um job de CI de divergência separado. - Faça commit da especificação gerada e dos tipos gerados do front-end junto com as alterações de origem. O CI regenera ambos e falha se as versões commitadas estiverem desatualizadas. - Os DTOs do cliente espelhados à mão permanecem uma fronteira manual deliberada e não são gerados. ## Use uma só solicitação de mudança (pull request) por tema - Crie a branch a partir da branch principal, a menos que você esteja explicitamente dando continuidade a um pull request existente. - Mantenha uma issue por pull request. Se for solicitado um trabalho separado, crie uma branch e um pull request separados. - Use prefixos convencionais de mensagem de commit, como feat, fix, docs, test e chore. - Explique as omissões intencionais no corpo do pull request, especialmente quando uma implementação anterior suportava mais comportamentos do que o domínio da reescrita atual suporta. - Execute primeiro os testes relevantes mais restritos e, em seguida, os comandos do repositório e de CI correspondentes à área que você alterou.