git:20260925.971e044 to git:20261025.9e7b1fb

70 added, 70 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: code-comments
description: >
- Define quando um comentário é permitido e quando é ruído em código TypeScript e
- NestJS. Elimina comentários óbvios que repetem o código, cabeçalhos de seção, imports
- explicados e narração de edições passadas. Estabelece o teste das três perguntas e o
- passe de poda obrigatório antes de fechar a tarefa. Use ao criar, editar ou revisar
- arquivos .ts, .json ou YAML.
+ Defines when a comment is allowed and when it is noise in TypeScript and NestJS
+ code. Eliminates obvious comments that repeat the code, section headers, explained
+ imports and narration of past edits. Establishes the three-question test and the
+ mandatory pruning pass before closing the task. Use when creating, editing or
+ reviewing .ts, .json or YAML files.
---
- # Comentários em código-fonte
+ # Source code comments
- > **Manutenção desta skill**
+ > **Maintaining this skill**
>
- > Atualize este documento sempre que mudar **qualquer regra descrita aqui**. O critério não
- > é *qual* regra — é a natureza da mudança: a política de comentários do projeto mudou →
- > atualize; refator técnico que preserva a política descrita → não toque.
+ > Update this document whenever **any rule described here** changes. The criterion is not
+ > *which* rule — it is the nature of the change: the project's comment policy changed →
+ > update; a technical refactor that preserves the described policy → leave it alone.
- Esta regra aplica-se a todo o repositório, em qualquer arquivo de código-fonte TypeScript
- (`*.ts`), configurações (`*.json`, `*.yaml`) e scripts.
+ This rule applies to the whole repository, in every TypeScript source file (`*.ts`),
+ configuration file (`*.json`, `*.yaml`) and script.
- ## O comentário é exceção, não hábito
+ ## A comment is the exception, not a habit
- Comentários devem ser evitados, a não ser que sejam estritamente necessários para explicar
- decisão não intuitiva, restrição técnica externa, tradeoff ou contexto inacessível apenas pela
- leitura do código. O código deve ser autoexplicativo através de nomes expressivos, tipos estritos
- e abstrações coesas.
+ Avoid comments unless they are strictly necessary to explain a non-intuitive decision, an
+ external technical constraint, a tradeoff or context that cannot be reached by reading the
+ code alone. The code must be self-explanatory through expressive names, strict types and
+ cohesive abstractions.
- Correto — explica contexto externo e restrição que o código não expressa sozinho:
+ Correct — explains external context and a constraint the code does not express on its own:
```typescript
/*
- * O SDK do ACP exige envio do cwd normalizado em formato POSIX para evitar falha
- * na resolução de caminhos em plataformas Windows e ambientes conteinerizados.
+ * The ACP SDK requires the cwd to be sent normalized in POSIX format to avoid
+ * path resolution failures on Windows platforms and containerized environments.
*/
const normalizedCwd = cwd.replace(/\\/g, '/');
```
- Evite — apenas repete a mecânica visível do código:
+ Avoid — merely repeats the visible mechanics of the code:
```typescript
- // substitui barras invertidas por barras normais
+ // replaces backslashes with forward slashes
const normalizedCwd = cwd.replace(/\\/g, '/');
```
- O nome do símbolo, a assinatura do método e os tipos do TypeScript são o canal primário de
- explicação. Antes de recorrer a um comentário, elimine a ambiguidade: renomeie a variável,
- extraia constantes para números ou strings mágicas, reforce os tipos ou extraia métodos
- privados na classe.
+ The symbol name, the method signature and the TypeScript types are the primary channel of
+ explanation. Before resorting to a comment, remove the ambiguity: rename the variable,
+ extract constants for magic numbers or strings, strengthen the types or extract private
+ methods in the class.
- ## Teste das três perguntas
+ ## Three-question test
- Submeta cada comentário pretendido às três perguntas abaixo antes de escrevê-lo. Se responder
- "não" a qualquer uma, **o comentário não entra**:
+ Submit every intended comment to the three questions below before writing it. If the answer
+ to any of them is "no", **the comment does not go in**:
- 1. **Ele diz algo que o código não diz?** Se a informação pode ser deduzida lendo os tipos, o
- nome do método ou as instruções seguintes, é ruído.
- 2. **Um leitor competente tentaria a alternativa que ele descarta?** Comentários que explicam
- "por que não fizemos X" só fazem sentido se X for uma abordagem atraente e comum que falha
- por uma razão não evidente.
- 3. **Ele continuará verdadeiro após a próxima refatoração?** Comentários que descrevem a ordem
- dos passos, nomes de variáveis ou fluxos internos viram mentiras assim que o código é
- refatorado. Apenas decisões duráveis sobrevivem.
+ 1. **Does it say something the code does not?** If the information can be inferred by reading
+ the types, the method name or the following statements, it is noise.
+ 2. **Would a competent reader try the alternative it rules out?** Comments explaining "why we
+ did not do X" only make sense if X is an attractive, common approach that fails for a
+ non-obvious reason.
+ 3. **Will it still be true after the next refactor?** Comments describing the order of steps,
+ variable names or internal flows become lies as soon as the code is refactored. Only
+ durable decisions survive.
- ## Catálogo de comentários proibidos
+ ## Catalog of forbidden comments
- Os casos a seguir exemplificam violações que devem ser ativamente eliminadas:
+ The following cases illustrate violations that must be actively eliminated:
- **Repetir a assinatura, classe ou nome do método:**
+ **Repeating the signature, class or method name:**
```typescript
- // busca o agente pelo id
+ // finds the agent by id
async findAgentById(id: string): Promise<AgentEntity> {
```
- **Comentar imports ou injeções de dependência no NestJS:**
+ **Commenting imports or dependency injections in NestJS:**
```typescript
- // importa o caso de uso de conexão
+ // imports the connection use case
import { ConnectAgentUseCase } from './connect-agent.use-case.ts';
- // injeta a porta do Discord
+ // injects the Discord port
@Inject(IDiscordPort)
private readonly discordPort: IDiscordPort,
```
- **Cabeçalhos de seção, divisores ou separadores visuais:**
+ **Section headers, dividers or visual separators:**
```typescript
// ==========================================
- // Handlers de Eventos
+ // Event Handlers
// ==========================================
- // Métodos Privados
+ // Private Methods
```
- **Nomear o passo trivial dentro de um método:**
+ **Naming a trivial step inside a method:**
```typescript
- // valida se o payload existe
+ // checks whether the payload exists
if (!payload) throw new BadRequestException();
- // chama o caso de uso
+ // calls the use case
await this.useCase.execute(payload);
```
- **JSDoc que apenas duplica informações de tipagem do TypeScript:**
+ **JSDoc that merely duplicates TypeScript type information:**
```typescript
/**
- * @param sessionId - O ID da sessão
- * @returns Retorna a sessão encontrada
+ * @param sessionId - The session ID
+ * @returns Returns the found session
*/
```
- **Comentários de TODO ou FIXME vagos e sem contexto:**
- Marcadores como `// TODO: ajustar depois` ou `// FIXME: erro aqui` sem descrição do critério
- de conclusão nem link para issue são proibidos. Débitos e pendências pertencem ao backlog ou
- à descrição de tarefas, não ao código-fonte.
+ **Vague TODO or FIXME comments without context:**
+ Markers such as `// TODO: fix later` or `// FIXME: error here` without a description of the
+ completion criterion or a link to an issue are forbidden. Debts and pending work belong to the
+ backlog or the task description, not to the source code.
- ## O comentário descreve o código de hoje
+ ## The comment describes today's code
- O leitor do código consulta o arquivo no presente, sem interesse no histórico de revisões que
- deram origem àquela linha.
+ The reader looks at the file in the present, with no interest in the revision history that
+ produced that line.
- - **Não comente a edição**: Explicações sobre abordagens anteriores descartadas, bugs antigos
- corrigidos ou justificativas de migração pertencem à mensagem de commit e ao Pull Request.
- - **Escreva a partir do resultado final**: Descreva a restrição como uma característica do
- código atual, e não como uma transição ("passou a ser", "deixou de usar").
+ - **Do not comment the edit**: Explanations about discarded previous approaches, old fixed bugs
+ or migration rationale belong to the commit message and the Pull Request.
+ - **Write from the final result**: Describe the constraint as a characteristic of the current
+ code, never as a transition ("became", "stopped using").
- ## Passe de poda antes de fechar a tarefa
+ ## Pruning pass before closing the task
- Antes de finalizar qualquer tarefa que inclua ou altere código:
+ Before finishing any task that adds or changes code:
- 1. Inspecione no diff (`git diff`) todas as linhas de comentário adicionadas.
- 2. Aplique o teste das três perguntas a cada uma delas.
- 3. Apague sem hesitar qualquer comentário redundante, explicativo de sintaxe ou narração de
- edição recente.
+ 1. Inspect every added comment line in the diff (`git diff`).
+ 2. Apply the three-question test to each one.
+ 3. Delete without hesitation any redundant comment, syntax explanation or narration of a
+ recent edit.