forjajs 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: release-auditor
3
+ description: Use ANTES de publicar no npm. Simula uma instalação limpa do tarball e valida que o files[] do package.json cobre tudo que os binários importam. Pega quebras que só apareceriam na máquina do usuário.
4
+ tools: Read, Bash, Grep
5
+ ---
6
+
7
+ Você é o **Release Auditor**. O Forja é publicado como `forjajs` no npm. Seu trabalho é
8
+ responder a uma única pergunta com evidência: **o pacote funciona na máquina de quem
9
+ instala?**
10
+
11
+ O repositório mente sobre isso. No repo, tudo resolve: `node_modules` existe com devDeps,
12
+ todos os arquivos estão presentes, o `cwd` é a raiz do projeto. Nada disso vale para quem
13
+ roda `npm i -g forjajs`. Duas classes de bug vivem exatamente nessa lacuna e só aparecem
14
+ em produção:
15
+
16
+ 1. **Arquivo fora do `files[]`** — o `package.json` lista os paths publicados à mão. Um
17
+ `import` para um arquivo não listado quebra só depois do publish.
18
+ 2. **Dependência de runtime declarada como `devDependency`** — não é instalada pelo
19
+ usuário. O comando estoura com `ERR_MODULE_NOT_FOUND`.
20
+
21
+ Grep e leitura de código não provam ausência dessas falhas. Instalação prova.
22
+
23
+ ## Procedimento
24
+
25
+ 1. **Empacote e instale de verdade**, num diretório temporário fora do repo:
26
+
27
+ ```bash
28
+ npm pack --pack-destination /tmp/forja-audit
29
+ cd /tmp/forja-audit && npm init -y && npm i ./forjajs-<versão>.tgz
30
+ ```
31
+
32
+ 2. **Exercite cada comando do registry**, não só o help. O help não carrega os scripts —
33
+ passa mesmo com tudo quebrado. Enumere os comandos e rode os que não têm efeito
34
+ colateral (leitura, status, query):
35
+
36
+ ```bash
37
+ npx forja # lista os comandos
38
+ npx forja query:universal teste
39
+ npx forja code:status
40
+ npx forja tools:doctor
41
+ ```
42
+
43
+ Um `ERR_MODULE_NOT_FOUND` aqui é reprovação imediata.
44
+
45
+ 3. **Cruze imports contra `files[]`.** Para cada binário em `bin/`, siga os imports
46
+ transitivamente e confirme que todo path resolvido cai sob um prefixo listado em
47
+ `files[]`. Reporte os que não caem.
48
+
49
+ 4. **Confira a fronteira deps/devDeps.** Todo pacote importado por código sob `files[]`
50
+ precisa estar em `dependencies`. `devDependencies` só pode ser importado por `test/`
51
+ e por scripts que não são publicados.
52
+
53
+ ```bash
54
+ grep -rn "from 'better-sqlite3'\|require('better-sqlite3')" bin/ lib/ scripts/
55
+ ```
56
+
57
+ ## Regras
58
+
59
+ - Output estruturado: ✓ aprovado / ✗ reprovado, com motivos numerados.
60
+ - Nunca rode `npm publish`. Você audita; publicar é decisão do usuário.
61
+ - Nunca aprove com base em leitura de código. Se você não instalou o tarball e rodou
62
+ um comando real, você não sabe — diga que não sabe.
63
+ - Limpe `/tmp/forja-audit` ao final.
64
+ - Se reprovar, aponte a linha exata: o import ofensor ou a entrada faltante no `files[]`.
@@ -22,10 +22,35 @@
22
22
  }
23
23
  ]
24
24
  }
25
+ ],
26
+ "PreToolUse": [
27
+ {
28
+ "matcher": "Edit|Write|NotebookEdit",
29
+ "hooks": [
30
+ {
31
+ "type": "command",
32
+ "command": "node $CLAUDE_PROJECT_DIR/scripts/hook-guard-paths.mjs",
33
+ "timeout": 5000
34
+ }
35
+ ]
36
+ }
37
+ ],
38
+ "PostToolUse": [
39
+ {
40
+ "matcher": "Edit|Write",
41
+ "hooks": [
42
+ {
43
+ "type": "command",
44
+ "command": "node $CLAUDE_PROJECT_DIR/scripts/hook-post-edit.mjs",
45
+ "timeout": 60000
46
+ }
47
+ ]
48
+ }
25
49
  ]
26
50
  },
27
51
  "permissions": {
28
52
  "allow": [
53
+ "Bash(node bin/forja.mjs *)",
29
54
  "Bash(node scripts/spec-cli.mjs *)",
30
55
  "Bash(node scripts/agent-router.mjs *)",
31
56
  "Bash(npm run spec:*)",
@@ -33,6 +58,16 @@
33
58
  "Bash(npm run sprint:*)",
34
59
  "Bash(npm run project:*)",
35
60
  "Bash(npm run context:*)",
61
+ "Bash(npm run code:*)",
62
+ "Bash(npm run design:*)",
63
+ "Bash(npm run gsd:*)",
64
+ "Bash(npm run ops:*)",
65
+ "Bash(npm run agent:*)",
66
+ "Bash(npm run catalog:*)",
67
+ "Bash(npm run workspace:*)",
68
+ "Bash(npm run hermes:handoff *)",
69
+ "Bash(npm run token:benchmark)",
70
+ "Bash(npm run tools:doctor)",
36
71
  "Bash(npm run sync:universal)",
37
72
  "Bash(npm run query:universal *)",
38
73
  "Bash(npm test)"
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: new-adr
3
+ description: Cria um ADR numerado em memory/90-decisions/ a partir do _template.md, preenchendo contexto, decisão, alternativas e consequências.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # Novo ADR
8
+
9
+ Registra uma decisão arquitetural em `memory/90-decisions/NNNN-titulo.md`.
10
+
11
+ Um ADR existe para preservar o **rationale**, não o resultado. O código já diz o que
12
+ foi feito; só o ADR diz por que as alternativas foram rejeitadas. Se não há alternativa
13
+ rejeitada, provavelmente não há decisão — e não há ADR a escrever.
14
+
15
+ ## Quando usar
16
+
17
+ Toda mudança estrutural: novo comando no core, mudança de contrato entre agentes,
18
+ troca de armazenamento, nova convenção de memória. O subagent `governance` reprova
19
+ merge de mudança estrutural sem ADR.
20
+
21
+ ## Passos
22
+
23
+ 1. **Descobrir o próximo número.** Nunca reutilize nem adivinhe:
24
+
25
+ ```bash
26
+ ls memory/90-decisions/ | grep -E '^[0-9]{4}-' | sort | tail -1
27
+ ```
28
+
29
+ O próximo é esse + 1, com zero-padding em 4 dígitos.
30
+
31
+ 2. **Verificar se já existe ADR sobre o tema.** Uma decisão que revisa outra não
32
+ ganha ADR novo do zero — ela *supersedes* a anterior:
33
+
34
+ ```bash
35
+ npm run query:universal "<tema da decisão>"
36
+ ```
37
+
38
+ Se encontrar, o ADR novo declara `superseded by` no antigo e o antigo passa a
39
+ `Status: superseded by ADR-NNNN`.
40
+
41
+ 3. **Copiar o template** `memory/90-decisions/_template.md` para o novo caminho.
42
+ O slug do arquivo é o título em kebab-case, sem artigos: `0021-guardrails-de-harness.md`.
43
+
44
+ 4. **Preencher.** Regras que importam:
45
+ - `Status`: `proposed` até haver merge; `accepted` depois.
46
+ - `Contexto`: o problema e as restrições. Sem solução aqui.
47
+ - `Decisão`: no imperativo, direto. "Adotar X", não "decidimos que talvez X".
48
+ - `Alternativas consideradas`: no mínimo uma, com o motivo real da rejeição.
49
+ "Rejeitada porque é pior" não é motivo.
50
+ - `Consequências`: inclua os trade-offs negativos. Um ADR só com positivas mente.
51
+ - `Rastreamento`: paths reais de implementação.
52
+
53
+ 5. **Reindexar a memória**, senão o ADR fica invisível para `query:universal`:
54
+
55
+ ```bash
56
+ npm run sync:universal
57
+ ```
58
+
59
+ 6. **Referenciar de volta.** Se o ADR muda uma convenção descrita no `CLAUDE.md`
60
+ ou no `AGENTS.md`, atualize esses arquivos no mesmo commit. Documentação que
61
+ contradiz o ADR é pior que documentação ausente.
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: new-command
3
+ description: Adiciona um comando ao core Forja (registry + alias npm + script + teste), respeitando a invariante do ADR-0020.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # Novo comando do core
8
+
9
+ O ADR-0020 estabelece uma invariante: **todo comando de processo passa por
10
+ `bin/forja.mjs`**. Não existe script solto. Adicionar um comando é um ato de quatro
11
+ partes acopladas — esquecer qualquer uma quebra `test/forja-core.test.js`.
12
+
13
+ ## As quatro partes
14
+
15
+ | Parte | Onde | Por quê |
16
+ |---|---|---|
17
+ | Entrada no registry | `lib/core/registry.mjs` | É a fonte da verdade: help, gates e auditoria derivam dela |
18
+ | Script alvo | `scripts/<nome>.mjs` | O trabalho de fato |
19
+ | Alias npm | `package.json` → `scripts` | Ergonomia; deve delegar ao core, nunca ao script direto |
20
+ | Teste | `test/forja-core.test.js` | Já cobre integridade automaticamente — só precisa passar |
21
+
22
+ ## Passos
23
+
24
+ 1. **Escolher o domínio.** Os válidos estão em `DOMAINS` no topo de
25
+ `lib/core/registry.mjs`: `workspace`, `sdd`, `gsd`, `design`, `code`, `memoria`,
26
+ `contexto`, `governanca`, `geracao`. Um domínio novo é mudança estrutural — peça
27
+ um ADR primeiro (skill `new-adr`).
28
+
29
+ 2. **Escrever o script** em `scripts/`. ESM, imports com prefixo `node:`, cabeçalho
30
+ comentando o *porquê* do script. Ele recebe os args depois de `args[]`.
31
+
32
+ 3. **Declarar no registry**, em ordem, dentro do bloco do domínio:
33
+
34
+ ```js
35
+ 'dominio:acao': {
36
+ domain: 'memoria',
37
+ desc: 'Frase curta no infinitivo, aparece no help',
38
+ node: 'scripts/meu-script.mjs',
39
+ args: ['subcomando'], // opcional: args fixos antes dos do usuário
40
+ gate: 'workspace', // opcional: 'workspace' | 'workspace-warn'
41
+ },
42
+ ```
43
+
44
+ Use `gate: 'workspace'` se o comando escreve no workspace externo (ADR-0019);
45
+ `workspace-warn` se apenas lê.
46
+
47
+ 4. **Adicionar o alias** em `package.json`. Ele delega ao core, nunca ao script:
48
+
49
+ ```json
50
+ "dominio:acao": "node bin/forja.mjs dominio:acao"
51
+ ```
52
+
53
+ Chamar `node scripts/meu-script.mjs` direto pula os gates e a auditoria em
54
+ `.context/forja-runs.jsonl` — é exatamente o que o ADR-0020 proíbe.
55
+
56
+ 5. **Verificar.** O hook `PostToolUse` já dispara o teste ao salvar o registry, mas
57
+ confirme o conjunto e o help:
58
+
59
+ ```bash
60
+ node --test test/forja-core.test.js
61
+ node bin/forja.mjs # o comando deve aparecer sob seu domínio
62
+ node bin/forja.mjs dominio:acao # execução real
63
+ ```
64
+
65
+ 6. **Permissão.** Se o comando será chamado por agentes, acrescente
66
+ `Bash(npm run dominio:*)` em `.claude/settings.json` → `permissions.allow`,
67
+ senão cada chamada vira um prompt.
package/README.md CHANGED
@@ -5,6 +5,7 @@
5
5
  </p>
6
6
 
7
7
  <p align="center">
8
+ <a href="https://www.npmjs.com/package/forjajs"><img src="https://img.shields.io/npm/v/forjajs?style=flat-square&color=cb3837&logo=npm" alt="npm"></a>
8
9
  <img src="https://github.com/allanpablo/forja/actions/workflows/ci.yml/badge.svg" alt="CI">
9
10
  <img src="https://img.shields.io/badge/operação-CLI--first-3553ff?style=flat-square" alt="CLI-first">
10
11
  <img src="https://img.shields.io/badge/agentes-6_papéis-orange?style=flat-square" alt="6 agentes">
@@ -85,6 +86,14 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
85
86
 
86
87
  ## ⚡ Quick start
87
88
 
89
+ ```bash
90
+ # Instalar (o pacote é forjajs; o comando é forja)
91
+ npm install -g forjajs
92
+ forja # help agrupado por domínio
93
+ ```
94
+
95
+ Ou clonando o repo:
96
+
88
97
  ```bash
89
98
  # Preparar o workspace de produção (canto fixo dos projetos)
90
99
  npm run workspace:init
@@ -0,0 +1,107 @@
1
+ # ADR-0021: Guardrails de harness e dependência de runtime explícita
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-09
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: harness, hooks, npm, memory, governance
7
+
8
+ ## Contexto
9
+
10
+ Três falhas silenciosas foram encontradas com o framework já publicado como `forjajs` no npm.
11
+ As três compartilham a mesma natureza: **erram sem avisar**. Nenhuma quebrava um teste,
12
+ nenhuma aparecia no `git status`, e todas produziam trabalho errado com aparência de trabalho certo.
13
+
14
+ 1. **`.mcp.json` com path absoluto obsoleto.** O codegraph era iniciado com
15
+ `-p /home/apk/.../2-Projeto-Agents/projects/forja`, uma cópia parada no commit `282c265`
16
+ (anterior ao ADR-0020). Consequência: `bin/forja.mjs` e `lib/core/` — o core inteiro que o
17
+ `CLAUDE.md` manda todo agente usar — eram invisíveis ao índice. Qualquer `codegraph_explore`
18
+ respondia sobre código morto, com confiança. O path também era versionado, quebrando para
19
+ qualquer outro contribuidor.
20
+
21
+ 2. **`better-sqlite3` como `devDependency`.** Dez scripts sob `files[]` a importam
22
+ estaticamente, e o pacote declarava zero `dependencies`. Numa instalação limpa
23
+ (`npm i -g forjajs`), `query:universal`, `sync:universal`, `context:smart`, `agent:route`,
24
+ `memory:compress` e `project:dashboard` estouravam com `ERR_MODULE_NOT_FOUND`. O `forja`
25
+ sem argumentos funcionava — o help não carrega os scripts — o que mascarava a quebra.
26
+
27
+ 3. **Regras de repositório existiam só como prosa.** `projects/` é declarado off-limits no
28
+ `CLAUDE.md`, e a invariante do ADR-0020 ("comando novo = entrada no registry") era validada
29
+ apenas no pre-commit via lefthook, que é opt-in. Ambas dependiam de a IA lembrar. Uma regra
30
+ que depende de memória não é uma regra; é uma sugestão.
31
+
32
+ 4. **Índice FTS5 cruzado com o conteúdo errado.** `sync-universal-memory.js` obtinha o id do nó
33
+ recém-gravado via `result.lastInsertRowid || SELECT id ...`. Num `INSERT ... ON CONFLICT DO
34
+ UPDATE` que *atualiza*, o SQLite não redefine `lastInsertRowid` — mantém o id do último INSERT
35
+ da conexão. Sendo truthy, o fallback nunca disparava. Toda execução com um insert seguido de
36
+ updates gravava o conteúdo de um documento sob o `node_id` de outro. Efeito medido: o ADR-0021
37
+ indexado com o corpo de "Harnesses: Hermes e GSD"; `query:universal "registry"` não encontrava
38
+ o ADR-0020; 135 linhas órfãs acumuladas. Como `query:universal` é o **primeiro passo** da
39
+ economia de tokens do ADR-0009, o framework vinha alimentando os agentes com o documento
40
+ errado — sem erro, sem log, sem sintoma.
41
+
42
+ ## Decisão
43
+
44
+ Mover a aplicação das regras do texto para o harness, e a verificação da publicação da leitura
45
+ para a execução.
46
+
47
+ - **`.mcp.json` sem `-p`.** Em modo MCP o codegraph resolve o projeto pelo `rootUri` do cliente.
48
+ Remover o path elimina a classe inteira de erro em vez de corrigir uma instância.
49
+ - **`better-sqlite3` em `dependencies`.** É dependência de runtime; era só declaração errada.
50
+ - **`PreToolUse` → `scripts/hook-guard-paths.mjs`.** Bloqueia escrita em `projects/` e
51
+ `docs/archive/` com exit 2, devolvendo o motivo e a alternativa. Falha aberta.
52
+ - **`PostToolUse` → `scripts/hook-post-edit.mjs`.** Ao editar `lib/core/registry.mjs` ou
53
+ `package.json`, roda `test/forja-core.test.js` na hora. A quebra chega junto da edição que
54
+ a causou, não commits depois.
55
+ - **`SessionStart` resiliente e honesto.** Todo acesso a SQLite passa a ser lazy — o hook
56
+ degradava para stack trace sem `node_modules`. Além disso, passa a avisar quando `memory/`
57
+ mudou depois do último `sync:universal`: índice defasado é a versão local do problema (1).
58
+ - **`RETURNING id` no upsert de `memory_nodes`.** Devolve a linha realmente afetada, inserida ou
59
+ atualizada, eliminando a dependência de `lastInsertRowid`. O sync passa a purgar linhas órfãs
60
+ do `search_idx` ao final, e o `title` volta a ser atualizado no conflito.
61
+ - **Subagent `release-auditor`.** Audita o pacote instalando o tarball de verdade e exercitando
62
+ comandos reais. Proibido aprovar por leitura de código.
63
+ - **Skills `new-adr` e `new-command`.** Os dois rituais do repo viram etapas executáveis.
64
+
65
+ ## Alternativas consideradas
66
+
67
+ - **Path relativo (`-p .`) no `.mcp.json`** — rejeitada porque ainda depende do `cwd` do processo
68
+ do servidor, que não é contratual. Omitir a flag delega ao protocolo, que é.
69
+ - **`better-sqlite3` como `optionalDependency` com degradação** — rejeitada porque a memória
70
+ hierárquica com FTS5 é a proposta central do Forja, não um extra. Um `forjajs` sem memória
71
+ não é uma instalação degradada; é uma instalação errada.
72
+ - **Manter as regras no `CLAUDE.md` e confiar na leitura do agente** — rejeitada por evidência:
73
+ as regras já estavam escritas e ainda assim o índice ficou apontando para a árvore errada por
74
+ mais de uma semana.
75
+ - **Rodar a suíte inteira no `PostToolUse`** — rejeitada por custo. O gate é `forja-core.test.js`,
76
+ um arquivo, poucos segundos. Um hook lento é um hook que alguém desliga.
77
+ - **Reconstruir o `search_idx` do zero a cada sync** — rejeitada porque esconderia a causa. O
78
+ índice ficaria correto sem que o upsert deixasse de devolver o id errado, e o próximo consumidor
79
+ de `lastInsertRowid` reencontraria o mesmo bug.
80
+
81
+ ## Consequências
82
+
83
+ **Positivas**:
84
+ - O pacote publicado passa a funcionar numa instalação limpa — verificado via `npm pack` + install.
85
+ - `query:universal` volta a devolver o documento que casou com a busca. Medido: 709 pares
86
+ título↔conteúdo alinhados, 0 cruzados, 0 órfãos (antes: 3 cruzados, 135 órfãos).
87
+ - Violações de `projects/` e do registry tornam-se impossíveis, não improváveis.
88
+ - O índice de memória defasado passa a se anunciar em vez de responder errado calado.
89
+ - Contribuidores externos clonam e o codegraph indexa o repo certo, sem editar nada.
90
+
91
+ **Negativas / Trade-offs**:
92
+ - `npm i forjajs` agora compila/baixa um módulo nativo (`better-sqlite3`): instalação mais lenta
93
+ e sujeita a prebuilds por plataforma. É o preço de o produto funcionar.
94
+ - O hook `PostToolUse` acrescenta poucos segundos a cada edição de `registry.mjs` ou `package.json`.
95
+ - Guardrails têm escape hatch (`FORJA_GUARD=0`, `FORJA_HOOK_TEST=0`). Um guard sem escape vira
96
+ um guard contornado por caminhos piores.
97
+ - `.claude/skills/` entra em `files[]`, aumentando o tarball.
98
+
99
+ ## Rastreamento
100
+ - Implementação: `.mcp.json`, `package.json`, `.claude/settings.json`,
101
+ `scripts/sync-universal-memory.js`, `scripts/hook-guard-paths.mjs`, `scripts/hook-post-edit.mjs`,
102
+ `scripts/hook-session-start.mjs`, `.claude/agents/release-auditor.md`,
103
+ `.claude/skills/new-adr/`, `.claude/skills/new-command/`
104
+ - Testes: `test/hooks.test.js`, `test/memory-index.test.js`
105
+ - ADRs relacionadas: ADR-0009 (economia de tokens — a corrupção do FTS a invalidava na prática),
106
+ ADR-0017 (codegraph no harness), ADR-0018 (ferramentas de processo),
107
+ ADR-0019 (workspace separado), ADR-0020 (forja core CLI única)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "Forja — framework CLI-first de orquestração multiagente, memória hierárquica e geração de projetos com IA",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -20,6 +20,7 @@
20
20
  "docs/",
21
21
  "specs/",
22
22
  ".claude/agents/",
23
+ ".claude/skills/",
23
24
  ".claude/settings.json",
24
25
  ".gemini-instructions.md",
25
26
  ".openai-instructions.md",
@@ -101,7 +102,9 @@
101
102
  },
102
103
  "author": "Allan Pablo",
103
104
  "license": "MIT",
104
- "devDependencies": {
105
- "better-sqlite3": "^12.11.1"
105
+ "dependencies": {
106
+ "better-sqlite3": "^12.11.1",
107
+ "otplib": "^13.4.1",
108
+ "qrcode": "^1.5.4"
106
109
  }
107
110
  }
@@ -0,0 +1,75 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Hook PreToolUse — guarda de caminhos protegidos (ADR-0021).
4
+ *
5
+ * O CLAUDE.md declara `projects/` off-limits e `docs/archive/` como material
6
+ * histórico congelado. Até aqui isso era prosa: valia enquanto a IA lembrasse.
7
+ * Este hook torna a regra determinística — a escrita é barrada antes de acontecer,
8
+ * não corrigida depois.
9
+ *
10
+ * Protocolo:
11
+ * - stdin: JSON com { tool_name, tool_input: { file_path }, cwd }
12
+ * - exit 0: liberado (silencioso)
13
+ * - exit 2: bloqueado — stderr volta para a IA como feedback acionável
14
+ *
15
+ * Escape hatch: FORJA_GUARD=0 desliga (útil para manutenção deliberada do archive).
16
+ */
17
+
18
+ import path from 'node:path';
19
+ import process from 'node:process';
20
+
21
+ /** Cada regra explica o porquê: a IA recebe o motivo, não só a negativa. */
22
+ const PROTECTED = [
23
+ {
24
+ test: (rel) => rel === 'projects' || rel.startsWith('projects/'),
25
+ reason:
26
+ 'projects/ é off-limits (CLAUDE.md): contém produtos em desenvolvimento ativo do usuário. ' +
27
+ 'Aplicações reais vivem no workspace externo — use `npm run project:new` (ADR-0019).',
28
+ },
29
+ {
30
+ test: (rel) => rel.startsWith('docs/archive/'),
31
+ reason:
32
+ 'docs/archive/ é material histórico congelado (ex.: legacy-bin/, mantido só para referência). ' +
33
+ 'Se a mudança é real, ela pertence ao código vivo em bin/ ou lib/.',
34
+ },
35
+ ];
36
+
37
+ function readStdin() {
38
+ return new Promise((resolve) => {
39
+ let data = '';
40
+ process.stdin.setEncoding('utf8');
41
+ process.stdin.on('data', (c) => { data += c; });
42
+ process.stdin.on('end', () => resolve(data));
43
+ });
44
+ }
45
+
46
+ /** Falha aberta: um guard quebrado não pode travar a sessão inteira. */
47
+ function allow() { process.exit(0); }
48
+
49
+ (async function main() {
50
+ if (process.env.FORJA_GUARD === '0') allow();
51
+
52
+ let payload;
53
+ try {
54
+ payload = JSON.parse(await readStdin());
55
+ } catch {
56
+ allow();
57
+ }
58
+
59
+ const filePath = payload?.tool_input?.file_path;
60
+ if (typeof filePath !== 'string' || !filePath) allow();
61
+
62
+ const root = process.env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
63
+ const abs = path.resolve(root, filePath);
64
+ const rel = path.relative(root, abs);
65
+
66
+ // Fora do repo: não é competência deste guard.
67
+ if (rel.startsWith('..') || path.isAbsolute(rel)) allow();
68
+
69
+ const relPosix = rel.split(path.sep).join('/');
70
+ const hit = PROTECTED.find((rule) => rule.test(relPosix));
71
+ if (!hit) allow();
72
+
73
+ process.stderr.write(`Escrita bloqueada em \`${relPosix}\`.\n\n${hit.reason}\n`);
74
+ process.exit(2);
75
+ })();
@@ -0,0 +1,79 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Hook PostToolUse — fecha o loop do registry (ADR-0021).
4
+ *
5
+ * ADR-0020 estabelece a invariante: "comando novo = entrada nova no registry".
6
+ * `test/forja-core.test.js` valida isso, mas só rodava no pre-commit — e o
7
+ * lefthook é opt-in, então na prática podia nunca rodar. Resultado: a quebra
8
+ * aparecia minutos ou commits depois, longe da edição que a causou.
9
+ *
10
+ * Aqui o teste roda no instante em que o registry (ou o package.json que o
11
+ * espelha) é tocado. Custo: um único arquivo de teste, poucos segundos.
12
+ *
13
+ * Protocolo:
14
+ * - stdin: JSON com { tool_name, tool_input: { file_path }, cwd }
15
+ * - exit 0: nada a fazer, ou teste passou (silencioso)
16
+ * - exit 2: teste falhou — stderr volta para a IA, que corrige antes de seguir
17
+ *
18
+ * Escape hatch: FORJA_HOOK_TEST=0 desliga.
19
+ */
20
+
21
+ import path from 'node:path';
22
+ import process from 'node:process';
23
+ import { spawnSync } from 'node:child_process';
24
+
25
+ /** Arquivos cuja edição invalida a integridade do core. */
26
+ const WATCHED = ['lib/core/registry.mjs', 'package.json'];
27
+ const SUITE = 'test/forja-core.test.js';
28
+
29
+ function readStdin() {
30
+ return new Promise((resolve) => {
31
+ let data = '';
32
+ process.stdin.setEncoding('utf8');
33
+ process.stdin.on('data', (c) => { data += c; });
34
+ process.stdin.on('end', () => resolve(data));
35
+ });
36
+ }
37
+
38
+ function skip() { process.exit(0); }
39
+
40
+ (async function main() {
41
+ if (process.env.FORJA_HOOK_TEST === '0') skip();
42
+
43
+ let payload;
44
+ try {
45
+ payload = JSON.parse(await readStdin());
46
+ } catch {
47
+ skip();
48
+ }
49
+
50
+ const filePath = payload?.tool_input?.file_path;
51
+ if (typeof filePath !== 'string' || !filePath) skip();
52
+
53
+ const root = process.env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
54
+ const rel = path.relative(root, path.resolve(root, filePath)).split(path.sep).join('/');
55
+ if (!WATCHED.includes(rel)) skip();
56
+
57
+ const res = spawnSync(process.execPath, ['--test', SUITE], {
58
+ cwd: root,
59
+ encoding: 'utf8',
60
+ // Evita recursão: o teste roda `bin/forja.mjs`, que não deve reentrar no hook.
61
+ env: { ...process.env, FORJA_HOOK_TEST: '0' },
62
+ });
63
+
64
+ if (res.status === 0) skip();
65
+
66
+ const detail = (res.stdout || '') + (res.stderr || '');
67
+ const failures = detail
68
+ .split('\n')
69
+ .filter((l) => /^not ok |^\s+error:|AssertionError/.test(l))
70
+ .slice(0, 12)
71
+ .join('\n');
72
+
73
+ process.stderr.write(
74
+ `\`${rel}\` foi editado e \`${SUITE}\` quebrou — a integridade do registry (ADR-0020) está violada.\n\n` +
75
+ `${failures || detail.slice(-1500)}\n\n` +
76
+ `Um comando novo precisa de: entrada em lib/core/registry.mjs + alias em package.json + script existente.\n`
77
+ );
78
+ process.exit(2);
79
+ })();
@@ -4,12 +4,15 @@
4
4
  *
5
5
  * Roda uma vez por sessão. Lê specs em aberto + handoffs pendentes do universal.db.
6
6
  * Output vai para additionalContext (carregado pelo Claude no system).
7
+ *
8
+ * Regra de ouro: este hook nunca pode derrubar a sessão. Todo acesso a SQLite é
9
+ * lazy e envolto em try/catch — sem `node_modules`, degrada para o modo só-specs
10
+ * em vez de abortar (ADR-0021).
7
11
  */
8
12
 
9
13
  import fs from 'node:fs';
10
14
  import path from 'node:path';
11
15
  import { fileURLToPath } from 'node:url';
12
- import { getDbPath, ensureSchema } from './memory-schema.mjs';
13
16
 
14
17
  const __filename = fileURLToPath(import.meta.url);
15
18
  const __dirname = path.dirname(__filename);
@@ -31,10 +34,18 @@ function listSpecs() {
31
34
  return out;
32
35
  }
33
36
 
34
- async function openHandoffs() {
35
- ensureSchema({ silent: true });
36
- const dbPath = getDbPath();
37
- if (!fs.existsSync(dbPath)) return [];
37
+ /** Lazy: sem better-sqlite3 instalado, devolve null em vez de estourar. */
38
+ async function resolveDbPath() {
39
+ try {
40
+ const { getDbPath, ensureSchema } = await import('./memory-schema.mjs');
41
+ ensureSchema({ silent: true });
42
+ const dbPath = getDbPath();
43
+ return fs.existsSync(dbPath) ? dbPath : null;
44
+ } catch { return null; }
45
+ }
46
+
47
+ async function openHandoffs(dbPath) {
48
+ if (!dbPath) return [];
38
49
  try {
39
50
  const { default: Database } = await import('better-sqlite3');
40
51
  const db = new Database(dbPath, { readonly: true });
@@ -44,11 +55,44 @@ async function openHandoffs() {
44
55
  } catch { return []; }
45
56
  }
46
57
 
58
+ /** mtime do arquivo .md mais recente sob memory/, ignorando o que é arquivado. */
59
+ function newestMemoryMtime(dir = path.join(root, 'memory'), acc = { t: 0 }) {
60
+ for (const entry of safeReadDir(dir)) {
61
+ if (entry.startsWith('.') || entry === 'archive') continue;
62
+ const p = path.join(dir, entry);
63
+ let st;
64
+ try { st = fs.statSync(p); } catch { continue; }
65
+ if (st.isDirectory()) newestMemoryMtime(p, acc);
66
+ else if (entry.endsWith('.md') && st.mtimeMs > acc.t) acc.t = st.mtimeMs;
67
+ }
68
+ return acc.t;
69
+ }
70
+
71
+ /**
72
+ * Índice defasado = `query:universal` responde sobre memória velha, calado.
73
+ * É a falha mais cara do framework: erra sem avisar. Então avisamos.
74
+ */
75
+ function staleIndex(dbPath) {
76
+ if (!dbPath) return false;
77
+ try {
78
+ const dbMtime = fs.statSync(dbPath).mtimeMs;
79
+ return newestMemoryMtime() > dbMtime;
80
+ } catch { return false; }
81
+ }
82
+
47
83
  (async function main() {
48
84
  const specs = listSpecs();
49
- const handoffs = await openHandoffs();
85
+ const dbPath = await resolveDbPath();
86
+ const handoffs = await openHandoffs(dbPath);
50
87
  const lines = ['<framework-status>'];
51
- lines.push(`Framework: 2-projeto-agents (SDD + orquestração)`);
88
+ lines.push(`Framework: forja (SDD + orquestração)`);
89
+
90
+ if (!dbPath) {
91
+ lines.push('\n⚠ Memória indisponível: universal.db não abriu. Rode `npm install` e `npm run sync:universal`.');
92
+ } else if (staleIndex(dbPath)) {
93
+ lines.push('\n⚠ Índice defasado: memory/ mudou depois do último sync. `query:universal` vai responder sobre memória velha — rode `npm run sync:universal`.');
94
+ }
95
+
52
96
  if (specs.length) {
53
97
  lines.push('\nSpecs ativas:');
54
98
  for (const s of specs) lines.push(` - ${s.slug} [${s.status}]`);
@@ -79,10 +79,15 @@ const db = new Database(dbPath);
79
79
  db.exec(schema);
80
80
 
81
81
  const upsertProject = db.prepare('INSERT INTO projects (name, path, created_at) VALUES (?, ?, ?) ON CONFLICT(name) DO UPDATE SET path=excluded.path');
82
- const upsertNode = db.prepare('INSERT INTO memory_nodes (project_id, path, kind, title, content, content_hash, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(path) DO UPDATE SET content=excluded.content, content_hash=excluded.content_hash, updated_at=excluded.updated_at');
82
+ // RETURNING id devolve a linha realmente afetada, inserida ou atualizada.
83
+ // Sem ele restaria `lastInsertRowid`, que num upsert-que-atualizou guarda o id do
84
+ // último INSERT da conexão — um id alheio, e o FTS acabava indexando o conteúdo de
85
+ // um documento sob o node_id de outro (ADR-0021).
86
+ const upsertNode = db.prepare('INSERT INTO memory_nodes (project_id, path, kind, title, content, content_hash, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(path) DO UPDATE SET title=excluded.title, content=excluded.content, content_hash=excluded.content_hash, updated_at=excluded.updated_at RETURNING id');
83
87
  const getProjectId = db.prepare('SELECT id FROM projects WHERE name = ?');
84
88
  const deleteFts = db.prepare('DELETE FROM search_idx WHERE node_id = ?');
85
89
  const insertFts = db.prepare('INSERT INTO search_idx (node_id, title, content) VALUES (?, ?, ?)');
90
+ const purgeFtsOrphans = db.prepare('DELETE FROM search_idx WHERE node_id NOT IN (SELECT id FROM memory_nodes)');
86
91
  const upsertSpecSummary = db.prepare(`
87
92
  INSERT INTO spec_summaries (slug, status, title, summary, source_path, updated_at)
88
93
  VALUES (?, ?, ?, ?, ?, ?)
@@ -219,9 +224,8 @@ function syncFiles(files, projectId = null) {
219
224
  const title = titleMatch ? titleMatch[1].trim() : path.basename(rel, '.md');
220
225
 
221
226
  try {
222
- const result = upsertNode.run(projectId, rel, getKind(rel), title, raw, hash, now);
223
- const nodeId = result.lastInsertRowid || db.prepare('SELECT id FROM memory_nodes WHERE path = ?').get(rel).id;
224
-
227
+ const { id: nodeId } = upsertNode.get(projectId, rel, getKind(rel), title, raw, hash, now);
228
+
225
229
  deleteFts.run(nodeId);
226
230
  insertFts.run(nodeId, title, raw);
227
231
  } catch (e) {
@@ -274,5 +278,9 @@ if (fs.existsSync(workspaceProjectsMemoryDir)) {
274
278
  syncFiles(fichaFiles);
275
279
  }
276
280
 
281
+ // Nós removidos deixam linhas órfãs no FTS: matches que apontam para nada.
282
+ const orphans = purgeFtsOrphans.run().changes;
283
+ if (orphans) log(`Índice FTS: ${orphans} linhas órfãs removidas`, 'info');
284
+
277
285
  db.close();
278
286
  log('Sincronização Universal Concluída!', 'success');