forjajs 1.7.1 → 1.7.3

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.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,59 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.7.3] — 2026-07-23 — Doctor: permissão/lock não é corrupção
8
+
9
+ O check `memory-db` (consumido por `tools:doctor` e pelo `SessionStart`) tratava **qualquer** falha
10
+ de abertura do `universal.db` como corrupção e prescrevia `sync:universal`. Num ambiente sem escrita
11
+ (sandbox, FS read-only, diretório protegido) o driver lança `SQLITE_CANTOPEN` — e a prescrição é
12
+ ativamente errada: `sync:universal` *escreve* no banco, reencenaria o mesmo erro sem curar nada, e
13
+ levaria o operador a "reindexar" um banco íntegro. Reportado a partir de uma sessão real em sandbox.
14
+
15
+ ### Corrigido
16
+ - **`memory-db` classifica a falha de abertura por `err.code`** em vez de colapsar tudo em
17
+ "corrompido" (ADR-0033):
18
+ - `SQLITE_CANTOPEN` / `EACCES` → **permissão/sandbox**, não corrupção; o fix orienta garantir
19
+ leitura no path e **desaconselha** `sync:universal`.
20
+ - `SQLITE_BUSY` → `warn` (lock temporário de outro processo; não trava o gate); o fix é aguardar.
21
+ - `SQLITE_CORRUPT` / `SQLITE_NOTADB` / resto → corrupção; fix `npm run sync:universal`.
22
+ O `err.code` já vinha impresso no `detail`, mas não decidia nada — a informação existia, faltava
23
+ ramificar. É a mesma classe do bug de ABI que motivou a SPEC-009, sobrevivendo dentro do arquivo
24
+ escrito para fechá-la.
25
+
26
+ ### Adicionado
27
+ - **ADR-0033** e quatro casos em `test/health.test.js` (CANTOPEN, EACCES, BUSY, NOTADB): a distinção
28
+ vira invariante que roda.
29
+
30
+ ---
31
+
32
+ ## [1.7.2] — 2026-07-22 — Fechando a classe: superfícies do projeto usam `cwd`
33
+
34
+ A auditoria sistemática dos comandos consumer-facing (o passo estrutural após os fixes caso-a-caso
35
+ de `spec:new`/`project:check`) achou **mais três instâncias vivas** da mesma classe — todas escondidas
36
+ num `const root = __dirname/..` que misturava "recurso do framework" com "projeto do usuário". Agora a
37
+ regra é explícita e tem gate (ADR-0032).
38
+
39
+ ### Corrigido
40
+ - **`gsd:plan`/`gsd:handoff`/`gsd:check`** (agent-harness) gravavam o runbook e liam `specs/` dentro
41
+ do pacote no consumidor; o `gsd:check` ainda spawava o `spec:check` com `cwd` do pacote e caminho
42
+ `.mjs` cravado (inexistente no dist). Agora operam em `process.cwd()` e resolvem o script via
43
+ `resolveScript` (`.ts` no dev, `.js` no dist).
44
+ - **`context:budget`/`agent:brief`/`context:sprint`** (context-ops) resolviam `.context/`, `specs/`,
45
+ `memory/` e o `.memoryrc.json` no pacote; o `cmdBudget` ainda validava travessia contra a raiz do
46
+ pacote e rejeitava arquivos do projeto. Agora usam `projectRoot = process.cwd()`; `catalog:*`
47
+ (recurso do framework) segue em `root`.
48
+ - **`design:check`** rejeitava o brief do consumidor ("caminho fora do projeto") por ancorar a
49
+ travessia no pacote — agora ancora no projeto.
50
+
51
+ ### Adicionado
52
+ - **Gate `consumer-project-surfaces`** no `release:check`: executa `gsd:plan` + `context:budget` no
53
+ cwd de um consumidor instalado e prova que o runbook cai em `<cwd>/.context/` e que o budget o lê de
54
+ lá. Testemunha cruzada, independente do banco — reprova a classe inteira antes do publish.
55
+ - **ADR-0032** e `test/consumer-project-surfaces.test.js`: a regra `projectRoot` (cwd) vs `root`
56
+ (framework) como invariante que roda. `sprint-manager` foi auditado e está são (opera pelo workspace).
57
+
58
+ ---
59
+
7
60
  ## [1.7.1] — 2026-07-22 — Correção: `project:check` em projetos consumidores
8
61
 
9
62
  ### Corrigido
package/README.en.md CHANGED
@@ -211,7 +211,7 @@ forja memory:extract # extract global knowledge from memor
211
211
 
212
212
  # Quality & release
213
213
  forja project:check # framework standards (pre-commit)
214
- forja tools:doctor # core X-ray; exit 1 if broken
214
+ forja tools:doctor # core X-ray; tells permission/lock from corruption; exit 1 if broken
215
215
  forja release:check --publish # tarball gate before publishing
216
216
  forja project:smoke # generated-project gate; --full installs and builds the backend
217
217
  forja project:dashboard # static status report
package/README.md CHANGED
@@ -201,7 +201,7 @@ forja memory:audit # coerência mapa↔código: mapa nã
201
201
 
202
202
  # Qualidade & release
203
203
  forja project:check # standards do framework (pre-commit)
204
- forja tools:doctor # raio-x do núcleo; exit 1 se quebrou
204
+ forja tools:doctor # raio-x do núcleo; separa permissão/lock de corrupção; exit 1 se quebrou
205
205
  forja release:check --publish # gate do tarball antes de publicar
206
206
  forja project:smoke # gate do projeto gerado; --full instala e builda o backend
207
207
  forja check:all # a bateria inteira de gates, um veredito; --full inclui os caros (SPEC-020)
@@ -139,8 +139,9 @@ const memoryDb = {
139
139
  fix: 'npm run sync:universal',
140
140
  };
141
141
  }
142
- // Existir não é abrir: um banco corrompido ou sem permissão dá o mesmo `existsSync` de um
143
- // banco saudável, e o operador merece saber qual dos dois é.
142
+ // Existir não é abrir: um banco corrompido, sem permissão ou travado dá o mesmo `existsSync`
143
+ // de um banco saudável. Os três reprovam a abertura por motivos opostos e pedem correções
144
+ // opostas — o `catch` abaixo classifica por `err.code`, nunca colapsa num "corrompido" único.
144
145
  const { default: Database } = await env.importModule('better-sqlite3');
145
146
  try {
146
147
  const db = new Database(dbPath, { readonly: true });
@@ -149,9 +150,30 @@ const memoryDb = {
149
150
  return { status: 'ok', detail: `${n} nós indexados`, fix: null };
150
151
  }
151
152
  catch (err) {
153
+ const code = asErrno(err).code || '';
154
+ // CANTOPEN/EACCES: o arquivo está íntegro, o processo é que não o alcança — sandbox, FS
155
+ // read-only, diretório sem permissão. sync:universal *escreve* no banco: prescrito aqui,
156
+ // reencenaria o mesmo CANTOPEN sem curar nada. Colapsar isso em "corrompido" é o bug que
157
+ // este ramo fecha — a integridade nunca foi tocada.
158
+ if (code === 'SQLITE_CANTOPEN' || code === 'EACCES') {
159
+ return {
160
+ status: 'fail',
161
+ detail: `banco existe mas não abre (${code}) — sem permissão de acesso, não corrupção`,
162
+ fix: `garanta leitura em ${dbPath} (sandbox? FS read-only?) — NÃO rode sync:universal`,
163
+ };
164
+ }
165
+ // BUSY: outro processo mantém o lock. O banco está são; esperar resolve.
166
+ if (code === 'SQLITE_BUSY') {
167
+ return {
168
+ status: 'warn',
169
+ detail: `banco ocupado (${code}) — outro processo o mantém travado`,
170
+ fix: 'aguarde o processo concorrente liberar o lock e rode de novo',
171
+ };
172
+ }
173
+ // Só o que sobra — SQLITE_CORRUPT, SQLITE_NOTADB, o resto — é integridade. Aí sim reindexar.
152
174
  return {
153
175
  status: 'fail',
154
- detail: `banco existe mas não abre (${asErrno(err).code || asErrno(err).message}) — provavelmente corrompido`,
176
+ detail: `banco existe mas não abre (${code || asErrno(err).message}) — provavelmente corrompido`,
155
177
  fix: 'npm run sync:universal',
156
178
  };
157
179
  }
@@ -466,6 +466,60 @@ const consumerProjectCheck = {
466
466
  return { status: 'ok', detail: 'project:check audita o cwd (o AGENTS.md do consumidor foi visto)', fix: null };
467
467
  },
468
468
  };
469
+ /**
470
+ * A mesma classe, generalizada além de `spec:new`/`project:check`: TODO comando que opera nas
471
+ * superfícies do projeto (`.context/`, `specs/`, `memory/`) tem de fazê-lo no cwd do consumidor, não
472
+ * no pacote. Aqui a testemunha é CRUZADA e independente do banco: `gsd:plan` grava o runbook em
473
+ * `<cwd>/.context/` (prova `agent-harness`), e `context:budget <slug>` só ACHA esse runbook se
474
+ * resolver o alvo por `projectRoot` (prova `context-ops`, cujo `cmdBudget` cravava `root`). Se qualquer
475
+ * um ainda usasse `__dirname/..`, o efeito cairia no pacote e o budget diria "nao encontrado".
476
+ */
477
+ const consumerProjectSurfaces = {
478
+ id: 'consumer-project-surfaces',
479
+ title: 'gsd:* e context:* operam nas superfícies do projeto (cwd), não do pacote',
480
+ severity: 'critical',
481
+ dependsOn: 'install',
482
+ probe(env) {
483
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
484
+ const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.forja;
485
+ const bin = path.join(env.pkgDir, binRel);
486
+ const slug = 'smoke-consumer-surface';
487
+ const runbookRel = path.join('.context', `gsd-${slug}.md`);
488
+ // context:budget grava um context_run no universal.db; contém o efeito num workspace descartável
489
+ // para não tocar o do runner (onde ensureSchema criaria um banco sem memory_nodes).
490
+ const opts = { cwd: env.installDir, env: { ...process.env, FORJA_WORKSPACE: path.join(env.installDir, '.forja-workspace') } };
491
+ // 1. gsd:plan grava o runbook — deve cair no cwd, nunca dentro do pacote.
492
+ env.spawn(process.execPath, [bin, 'gsd:plan', slug, 'objetivo de fumaça'], opts);
493
+ const noProjeto = env.fs.existsSync(path.join(env.installDir, runbookRel));
494
+ const noPacote = env.fs.existsSync(path.join(env.pkgDir, runbookRel))
495
+ || env.fs.existsSync(path.join(env.pkgDir, 'dist', runbookRel));
496
+ if (noPacote) {
497
+ return {
498
+ status: 'fail',
499
+ detail: 'gsd:plan gravou o runbook DENTRO de node_modules/forjajs — opera no mundo errado',
500
+ fix: 'agent-harness deve usar projectRoot=process.cwd() para .context/ e specs/, não __dirname/..',
501
+ };
502
+ }
503
+ if (!noProjeto) {
504
+ return {
505
+ status: 'fail',
506
+ detail: 'gsd:plan não gravou o runbook em <cwd>/.context/ — a raiz do projeto está errada',
507
+ fix: 'confira projectRoot no agent-harness (cmdGsdPlan)',
508
+ };
509
+ }
510
+ // 2. context:budget precisa ACHAR o runbook que o gsd escreveu no cwd — só acha via projectRoot.
511
+ const budget = env.spawn(process.execPath, [bin, 'context:budget', slug], opts);
512
+ const saida = `${budget.stdout || ''}${budget.stderr || ''}`;
513
+ if (/nao encontrado|não encontrado|fora do projeto/i.test(saida)) {
514
+ return {
515
+ status: 'fail',
516
+ detail: 'context:budget não achou o runbook do cwd — está resolvendo o alvo dentro do pacote',
517
+ fix: 'context-ops deve resolver .context/specs/memory por projectRoot=process.cwd(), não por root',
518
+ };
519
+ }
520
+ return { status: 'ok', detail: 'gsd:plan grava no cwd e context:budget o lê de lá — superfícies no projeto', fix: null };
521
+ },
522
+ };
469
523
  /** @type {import('./checks.ts').Check[]} */
470
524
  export const RELEASE_CHECKS = [
471
525
  treeClean,
@@ -474,6 +528,7 @@ export const RELEASE_CHECKS = [
474
528
  smokeCommands,
475
529
  consumerSpecNew,
476
530
  consumerProjectCheck,
531
+ consumerProjectSurfaces,
477
532
  importsResolve,
478
533
  depsDeclared,
479
534
  depsUnused,
@@ -4,8 +4,13 @@ import path from 'node:path';
4
4
  import { spawnSync } from 'node:child_process';
5
5
  import { fileURLToPath } from 'node:url';
6
6
  import { initWorkspace, getWorkspaceInfo, listProjects, resolveProject, getWorkspaceProjectsMemoryDir, } from "../lib/workspace.js";
7
+ import { resolveScript } from "../lib/core/registry.js";
7
8
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
9
+ // `root` = recursos do FRAMEWORK (ex.: design:* lê design-md/) — resolvidos por __dirname.
10
+ // `projectRoot` = o PROJETO do usuário (gsd:* opera em specs/ e .context/ dele) — onde foi invocado.
11
+ // Sem essa separação o gsd escrevia no PACOTE no consumidor (classe spec-cli v1.6.2/check-standards v1.7.1).
8
12
  const root = path.resolve(__dirname, '..');
13
+ const projectRoot = process.cwd();
9
14
  const DESIGN_REQUIRED = [
10
15
  'Feature/superficie',
11
16
  'Persona principal',
@@ -69,8 +74,10 @@ function rel(file) {
69
74
  return path.relative(root, file);
70
75
  }
71
76
  function readText(file) {
72
- const full = path.resolve(root, file);
73
- if (!full.startsWith(root))
77
+ // O brief do `design:check` é do PROJETO do usuário (cwd), não do pacote — a âncora e o guardrail
78
+ // de travessia são o projectRoot. Cravar `root` rejeitava o brief do consumidor ("fora do projeto").
79
+ const full = path.resolve(projectRoot, file);
80
+ if (!full.startsWith(projectRoot))
74
81
  fail(`Caminho fora do projeto: ${file}`);
75
82
  if (!fs.existsSync(full))
76
83
  fail(`Arquivo nao encontrado: ${file}`);
@@ -264,15 +271,15 @@ function appendHandoff(payload) {
264
271
  function cmdGsdPlan([slug = 'run', ...goalParts]) {
265
272
  const goal = goalParts.join(' ') || 'execucao orientada por agentes';
266
273
  const safeSlug = slug.toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
267
- const outDir = path.join(root, '.context');
274
+ const outDir = path.join(projectRoot, '.context');
268
275
  fs.mkdirSync(outDir, { recursive: true });
269
276
  const outFile = path.join(outDir, `gsd-${safeSlug}.md`);
270
- const specPath = path.join(root, 'specs', safeSlug, 'spec.md');
277
+ const specPath = path.join(projectRoot, 'specs', safeSlug, 'spec.md');
271
278
  const hasSpec = fs.existsSync(specPath);
272
279
  const content = `# GSD Runbook: ${safeSlug}
273
280
 
274
281
  - **Objetivo**: ${goal}
275
- - **Spec**: ${hasSpec ? rel(specPath) : 'nao encontrada'}
282
+ - **Spec**: ${hasSpec ? path.relative(projectRoot, specPath) : 'nao encontrada'}
276
283
  - **Gerado em**: ${new Date().toISOString()}
277
284
 
278
285
  ## Gates
@@ -304,7 +311,7 @@ function cmdGsdPlan([slug = 'run', ...goalParts]) {
304
311
  - Rode \`npm run gsd:check -- ${safeSlug} <brief.md>\` antes de entregar para Governance.
305
312
  `;
306
313
  fs.writeFileSync(outFile, content, 'utf8');
307
- console.log(`GSD runbook criado: ${rel(outFile)}`);
314
+ console.log(`GSD runbook criado: ${path.relative(projectRoot, outFile)}`);
308
315
  if (!hasSpec)
309
316
  console.log(`Aviso: spec nao encontrada em specs/${safeSlug}/spec.md`);
310
317
  }
@@ -315,12 +322,12 @@ function cmdGsdHandoff([phase, slug, ...contextParts]) {
315
322
  if (!template)
316
323
  fail(`Fase invalida: ${phase}. Use: ${Object.keys(GSD_HANDOFFS).join('|')}`);
317
324
  const safeSlug = slug.toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
318
- const specDir = path.join(root, 'specs', safeSlug);
319
- const runbook = path.join(root, '.context', `gsd-${safeSlug}.md`);
325
+ const specDir = path.join(projectRoot, 'specs', safeSlug);
326
+ const runbook = path.join(projectRoot, '.context', `gsd-${safeSlug}.md`);
320
327
  const contextExtra = contextParts.join(' ').trim();
321
328
  const context = [
322
329
  fs.existsSync(specDir) ? `specs/${safeSlug}` : `specs/${safeSlug} (nao encontrado)`,
323
- fs.existsSync(runbook) ? rel(runbook) : `.context/gsd-${safeSlug}.md (nao encontrado)`,
330
+ fs.existsSync(runbook) ? path.relative(projectRoot, runbook) : `.context/gsd-${safeSlug}.md (nao encontrado)`,
324
331
  contextExtra,
325
332
  ].filter(Boolean).join('; ');
326
333
  const payload = {
@@ -335,20 +342,24 @@ function cmdGsdCheck([slug, briefPath]) {
335
342
  fail('Uso: agent-harness gsd:check <slug> [brief.md]');
336
343
  const safeSlug = slug.toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
337
344
  const checks = [];
338
- const runbook = path.join(root, '.context', `gsd-${safeSlug}.md`);
345
+ const runbook = path.join(projectRoot, '.context', `gsd-${safeSlug}.md`);
339
346
  checks.push({
340
347
  name: 'GSD runbook',
341
348
  ok: fs.existsSync(runbook),
342
- detail: rel(runbook),
349
+ detail: path.relative(projectRoot, runbook),
343
350
  });
344
- const specDir = path.join(root, 'specs', safeSlug);
351
+ const specDir = path.join(projectRoot, 'specs', safeSlug);
345
352
  checks.push({
346
353
  name: 'Spec directory',
347
354
  ok: fs.existsSync(specDir),
348
355
  detail: `specs/${safeSlug}`,
349
356
  });
350
- const specCheck = spawnSync('node', ['scripts/spec-cli.mjs', 'check', safeSlug], {
351
- cwd: root,
357
+ // O spec:check tem de rodar no PROJETO do usuário (cwd), não no pacote, e resolver o script pela
358
+ // extensão certa (`.ts` no dev, `.js` no dist publicado). Cravar `cwd: root` + `scripts/spec-cli.mjs`
359
+ // auditava/carregava o pacote no consumidor (mesma classe spec-cli v1.6.2).
360
+ const specCli = resolveScript(root, 'scripts/spec-cli');
361
+ const specCheck = spawnSync(process.execPath, [specCli, 'check', safeSlug], {
362
+ cwd: projectRoot,
352
363
  encoding: 'utf8',
353
364
  });
354
365
  checks.push({
@@ -5,14 +5,19 @@ import Database from 'better-sqlite3';
5
5
  import { fileURLToPath } from 'node:url';
6
6
  import { ensureSchema, getDbPath } from "./memory-schema.js";
7
7
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
8
+ // `root` = recursos do FRAMEWORK (catalog: boilerplates/, design-md/) — resolvidos por __dirname.
9
+ // `projectRoot` = o PROJETO do usuário (.context/, specs/, memory/, .memoryrc.json) — onde foi invocado.
10
+ // Cravar `root` para as superfícies do projeto auditava/gravava no PACOTE no consumidor (classe de bug
11
+ // spec-cli v1.6.2 / check-standards v1.7.1). No repo do framework os dois coincidem (cwd = raiz).
8
12
  const root = path.resolve(__dirname, '..');
9
- const outDir = path.join(root, '.context');
13
+ const projectRoot = process.cwd();
14
+ const outDir = path.join(projectRoot, '.context');
10
15
  const defaultLimit = readTokenLimit();
11
16
  function estimateTokens(content) {
12
17
  return Math.ceil(content.length / 4);
13
18
  }
14
19
  function readTokenLimit() {
15
- const configPath = path.join(root, '.memoryrc.json');
20
+ const configPath = path.join(projectRoot, '.memoryrc.json');
16
21
  if (!fs.existsSync(configPath))
17
22
  return 8000;
18
23
  try {
@@ -27,7 +32,7 @@ function ensureOutDir() {
27
32
  fs.mkdirSync(outDir, { recursive: true });
28
33
  }
29
34
  function readIfExists(relPath, maxChars = 12000) {
30
- const full = path.join(root, relPath);
35
+ const full = path.join(projectRoot, relPath);
31
36
  if (!fs.existsSync(full))
32
37
  return '';
33
38
  return fs.readFileSync(full, 'utf8').slice(0, maxChars);
@@ -47,7 +52,7 @@ function extractSection(content, heading, maxChars = 2200) {
47
52
  return match ? match[1].trim().slice(0, maxChars) : '';
48
53
  }
49
54
  function listSpecs() {
50
- const specsDir = path.join(root, 'specs');
55
+ const specsDir = path.join(projectRoot, 'specs');
51
56
  if (!fs.existsSync(specsDir))
52
57
  return [];
53
58
  return fs.readdirSync(specsDir, { withFileTypes: true })
@@ -64,7 +69,7 @@ function listSpecs() {
64
69
  status: spec ? specStatus(spec) : 'missing',
65
70
  hasPlan: fs.existsSync(planPath),
66
71
  hasTasks: fs.existsSync(tasksPath),
67
- path: path.relative(root, specPath),
72
+ path: path.relative(projectRoot, specPath),
68
73
  };
69
74
  });
70
75
  }
@@ -80,7 +85,7 @@ function recordContextRun(kind, slug, filePath, content, limitTokens = null) {
80
85
  db.prepare(`
81
86
  INSERT INTO context_runs (created_at, kind, slug, path, bytes, estimated_tokens, limit_tokens, status)
82
87
  VALUES (?, ?, ?, ?, ?, ?, ?, ?)
83
- `).run(new Date().toISOString(), kind, slug || null, path.relative(root, filePath), content.length, tokens, limitTokens, status);
88
+ `).run(new Date().toISOString(), kind, slug || null, path.relative(projectRoot, filePath), content.length, tokens, limitTokens, status);
84
89
  db.close();
85
90
  }
86
91
  function upsertSpecSummary(slug, content) {
@@ -123,7 +128,7 @@ function getOpenHandoffs(slug = null) {
123
128
  return rows;
124
129
  }
125
130
  function latestAdrs() {
126
- const dir = path.join(root, 'memory', '90-decisions');
131
+ const dir = path.join(projectRoot, 'memory', '90-decisions');
127
132
  if (!fs.existsSync(dir))
128
133
  return [];
129
134
  return fs.readdirSync(dir)
@@ -148,8 +153,8 @@ function cmdBudget([target, limitArg]) {
148
153
  `.context/agent-brief-${target}.md`,
149
154
  `.context/context-task.md`,
150
155
  ];
151
- const file = candidates.map((candidate) => path.resolve(root, candidate)).find((candidate) => fs.existsSync(candidate));
152
- if (!file || !file.startsWith(root)) {
156
+ const file = candidates.map((candidate) => path.resolve(projectRoot, candidate)).find((candidate) => fs.existsSync(candidate));
157
+ if (!file || !file.startsWith(projectRoot)) {
153
158
  console.error(`Arquivo ou slug nao encontrado: ${target}`);
154
159
  process.exit(1);
155
160
  }
@@ -157,7 +162,7 @@ function cmdBudget([target, limitArg]) {
157
162
  const tokens = estimateTokens(content);
158
163
  const status = tokens <= limit ? 'OK' : 'FAIL';
159
164
  recordContextRun('budget', path.basename(target), file, content, limit);
160
- console.log(`${status} ${path.relative(root, file)}: ${tokens} tokens estimados / limite ${limit}`);
165
+ console.log(`${status} ${path.relative(projectRoot, file)}: ${tokens} tokens estimados / limite ${limit}`);
161
166
  if (tokens > limit)
162
167
  process.exit(1);
163
168
  }
@@ -189,7 +194,7 @@ function cmdSprintPack() {
189
194
  const outFile = path.join(outDir, 'sprint-pack.md');
190
195
  fs.writeFileSync(outFile, md, 'utf8');
191
196
  recordContextRun('sprint-pack', null, outFile, md, defaultLimit);
192
- console.log(`Sprint pack gerado: ${path.relative(root, outFile)} (${estimateTokens(md)} tokens estimados)`);
197
+ console.log(`Sprint pack gerado: ${path.relative(projectRoot, outFile)} (${estimateTokens(md)} tokens estimados)`);
193
198
  }
194
199
  function cmdAgentBrief([role, slug]) {
195
200
  if (!role || !slug) {
@@ -234,7 +239,7 @@ function cmdAgentBrief([role, slug]) {
234
239
  const outFile = path.join(outDir, `agent-brief-${role}-${slug}.md`);
235
240
  fs.writeFileSync(outFile, md, 'utf8');
236
241
  recordContextRun('agent-brief', slug, outFile, md, defaultLimit);
237
- console.log(`Agent brief gerado: ${path.relative(root, outFile)} (${estimateTokens(md)} tokens estimados)`);
242
+ console.log(`Agent brief gerado: ${path.relative(projectRoot, outFile)} (${estimateTokens(md)} tokens estimados)`);
238
243
  }
239
244
  function summarizeReadme(relPath) {
240
245
  const content = readIfExists(relPath, 2500);
@@ -0,0 +1,63 @@
1
+ # ADR-0032: superfícies do projeto usam `cwd`; recursos do framework usam `__dirname`
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-22
5
+ - **Autor(es)**: apk
6
+ - **Tags**: cli, consumer, dist, invariants, release-gate
7
+
8
+ ## Contexto
9
+
10
+ Uma mesma classe de bug voltou quatro vezes: um comando funciona no repo do framework (onde `cwd`
11
+ e `__dirname/..` coincidem) e quebra no pacote **publicado** de um consumidor, porque resolve as
12
+ superfícies do projeto do usuário por `__dirname`, apontando para `node_modules/forjajs/dist`.
13
+ Já mordeu `spec:new` (v1.6.2, escrevia dentro do pacote), `project:upgrade` (v1.6.0, extensão `.ts`
14
+ cravada) e `project:check` (v1.7.1, auditava o pacote — travou uma corrida do `orchestrate`).
15
+
16
+ Corrigir caso a caso não fecha a classe. Uma auditoria sistemática dos comandos consumer-facing
17
+ revelou **mais três instâncias vivas**, todas escondidas atrás de um `const root = __dirname/..` que
18
+ misturava dois papéis: em `agent-harness` o `gsd:*`/`design:check` gravavam/liam no pacote; em
19
+ `context-ops` o `cmdBudget` resolvia o alvo e o guardrail de travessia contra o pacote. `sprint-manager`
20
+ saiu limpo — ele opera pelo workspace (`resolveProject`/`getWorkspaceRoot`, caminhos absolutos).
21
+
22
+ ## Decisão
23
+
24
+ Todo script separa **dois papéis de raiz**, com nomes distintos:
25
+
26
+ - **`root` = recursos do FRAMEWORK** (templates, `design-md/`, `boilerplates/`, `specs/_templates`) —
27
+ resolvidos por `__dirname`, porque viajam dentro do pacote.
28
+ - **`projectRoot = process.cwd()` = o PROJETO do usuário** (`.context/`, `specs/`, `memory/`,
29
+ `.memoryrc.json`, briefs) — onde o comando foi invocado.
30
+
31
+ Cravar `__dirname/..` para uma superfície do projeto é o bug; cravar `cwd` para um recurso do
32
+ framework é o bug espelhado. O nome da variável passa a **declarar** o papel — some o `root`
33
+ ambíguo que dava para ler dos dois jeitos.
34
+
35
+ A regra vira **invariante que roda**: o gate `consumer-project-surfaces` (em `release:check`) empacota,
36
+ instala isolado e EXECUTA `gsd:plan` + `context:budget` no cwd do consumidor, conferindo que o runbook
37
+ cai em `<cwd>/.context/` e que o budget o encontra de lá. Testemunha cruzada e independente do banco.
38
+
39
+ ## Alternativas consideradas
40
+ - **Só corrigir os dois novos offenders** — rejeitada: é o caso-a-caso que deixou a classe reabrir.
41
+ - **Um único `root` esperto (heurística cwd-vs-pacote)** — rejeitada: a ambiguidade É o bug; dois
42
+ nomes explícitos custam nada e removem a decisão do call site.
43
+ - **Gate só a nível de fonte (grep de `__dirname`)** — rejeitada como suficiente: `__dirname` é
44
+ legítimo para recursos do framework; só EXECUTAR no mundo do consumidor separa certo de errado.
45
+
46
+ ## Consequências
47
+
48
+ **Positivas**:
49
+ - `gsd:*`, `context:*`, `design:check` passam a operar no projeto do consumidor, como já faziam
50
+ `spec:new`/`project:check`.
51
+ - A classe inteira ganha um gate que a reprova antes do publish — não depende de um consumidor relatar.
52
+ - O código fica auto-documentado: `projectRoot` vs `root` diz o papel sem comentário.
53
+
54
+ **Negativas / Trade-offs**:
55
+ - `catalog:*` (varre `boilerplates/`/`design-md/` do framework) só faz sentido rodado do repo; no
56
+ pacote publicado é inócuo — aceitável, é comando de manutenção, não de consumidor.
57
+ - O gate custa um `npm pack` + install por corrida de `release:check` (já era o caso dos outros dois).
58
+
59
+ ## Rastreamento
60
+ - Implementação: `scripts/agent-harness.ts`, `scripts/context-ops.ts`, `lib/core/release.ts`
61
+ (`consumerProjectSurfaces`), `test/consumer-project-surfaces.test.js`
62
+ - ADRs relacionadas: ADR-0021 (invariante > disciplina), ADR-0026 (dual-runtime TS), ADR-0031 (motor
63
+ de orquestração — a corrida que o bug do `project:check` travou)
@@ -0,0 +1,64 @@
1
+ # ADR-0033: `memory-db` distingue permissão/lock de corrupção
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-23
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: doctor, memory, diagnostics, sqlite
7
+
8
+ ## Contexto
9
+
10
+ O check `memory-db` (`lib/core/health.ts`), consumido por `tools:doctor` e pelo hook
11
+ `SessionStart`, abria `universal.db` e tratava **qualquer** exceção do `better-sqlite3` como
12
+ corrupção:
13
+
14
+ ```ts
15
+ } catch (err) {
16
+ return {
17
+ status: 'fail',
18
+ detail: `... (${asErrno(err).code}) — provavelmente corrompido`,
19
+ fix: 'npm run sync:universal',
20
+ };
21
+ }
22
+ ```
23
+
24
+ O `err.code` — que já distingue os casos — estava impresso no `detail`, mas não decidia nada.
25
+ Num ambiente sem permissão de escrita (sandbox, FS read-only, diretório protegido) o driver
26
+ lança `SQLITE_CANTOPEN`, e o doctor diagnosticava "provavelmente corrompido" prescrevendo
27
+ `sync:universal`. A prescrição é ativamente errada: `sync:universal` **escreve** no banco — no
28
+ mesmo ambiente ele reencena o `CANTOPEN` sem curar nada, e ainda confunde o operador levando-o a
29
+ "reindexar" um banco íntegro. Reportado a partir de uma sessão real em sandbox restrito.
30
+
31
+ É a violação do princípio 1 do próprio `health.ts` ("nunca colapsar causas distintas num
32
+ booleano"), a mesma classe do bug de ABI que motivou a SPEC-009 — sobrevivendo dentro do arquivo
33
+ escrito para fechá-la.
34
+
35
+ ## Decisão
36
+
37
+ Classificar a falha de abertura por `err.code`, uma causa por prescrição:
38
+
39
+ - `SQLITE_CANTOPEN` / `EACCES` → `fail`, **permissão/sandbox**, não corrupção; fix orienta
40
+ garantir leitura no path e **desaconselha** `sync:universal`.
41
+ - `SQLITE_BUSY` → `warn` (lock temporário de outro processo; não trava o gate); fix é aguardar.
42
+ - Resto (`SQLITE_CORRUPT`, `SQLITE_NOTADB`, …) → `fail`, **corrupção**; fix `npm run sync:universal`.
43
+
44
+ ## Alternativas consideradas
45
+
46
+ - **Testar a integridade com `PRAGMA quick_check` antes de classificar** — rejeitada: um banco que
47
+ nem abre (CANTOPEN) não chega ao pragma; o `err.code` da abertura já carrega a distinção sem I/O extra.
48
+ - **Discriminar por mensagem de erro** — rejeitada: mensagens do SQLite variam entre versões e
49
+ locale; `err.code` é o contrato estável, como o resto do `health.ts` já assume.
50
+
51
+ ## Consequências
52
+
53
+ **Positivas**:
54
+ - Sandbox/permissão deixa de ser confundido com corrupção; o operador recebe a correção da causa real.
55
+ - `sync:universal` nunca é prescrito para um banco íntegro-mas-inacessível.
56
+ - Lock concorrente vira `warn`, não reprova o núcleo.
57
+
58
+ **Negativas / Trade-offs**:
59
+ - Mais um `err.code` (`SQLITE_BUSY`) a manter caso o driver mude a taxonomia — coberto por teste.
60
+
61
+ ## Rastreamento
62
+ - Implementação: `lib/core/health.ts` (check `memory-db`)
63
+ - Testes: `test/health.test.js` (CANTOPEN, EACCES, BUSY, NOTADB)
64
+ - ADRs relacionadas: ADR-0023 (doctor como gate do núcleo), SPEC-009 (doctor-do-nucleo)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.7.1",
3
+ "version": "1.7.3",
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",