forjajs 1.7.0 → 1.7.2

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,49 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.7.2] — 2026-07-22 — Fechando a classe: superfícies do projeto usam `cwd`
8
+
9
+ A auditoria sistemática dos comandos consumer-facing (o passo estrutural após os fixes caso-a-caso
10
+ de `spec:new`/`project:check`) achou **mais três instâncias vivas** da mesma classe — todas escondidas
11
+ num `const root = __dirname/..` que misturava "recurso do framework" com "projeto do usuário". Agora a
12
+ regra é explícita e tem gate (ADR-0032).
13
+
14
+ ### Corrigido
15
+ - **`gsd:plan`/`gsd:handoff`/`gsd:check`** (agent-harness) gravavam o runbook e liam `specs/` dentro
16
+ do pacote no consumidor; o `gsd:check` ainda spawava o `spec:check` com `cwd` do pacote e caminho
17
+ `.mjs` cravado (inexistente no dist). Agora operam em `process.cwd()` e resolvem o script via
18
+ `resolveScript` (`.ts` no dev, `.js` no dist).
19
+ - **`context:budget`/`agent:brief`/`context:sprint`** (context-ops) resolviam `.context/`, `specs/`,
20
+ `memory/` e o `.memoryrc.json` no pacote; o `cmdBudget` ainda validava travessia contra a raiz do
21
+ pacote e rejeitava arquivos do projeto. Agora usam `projectRoot = process.cwd()`; `catalog:*`
22
+ (recurso do framework) segue em `root`.
23
+ - **`design:check`** rejeitava o brief do consumidor ("caminho fora do projeto") por ancorar a
24
+ travessia no pacote — agora ancora no projeto.
25
+
26
+ ### Adicionado
27
+ - **Gate `consumer-project-surfaces`** no `release:check`: executa `gsd:plan` + `context:budget` no
28
+ cwd de um consumidor instalado e prova que o runbook cai em `<cwd>/.context/` e que o budget o lê de
29
+ lá. Testemunha cruzada, independente do banco — reprova a classe inteira antes do publish.
30
+ - **ADR-0032** e `test/consumer-project-surfaces.test.js`: a regra `projectRoot` (cwd) vs `root`
31
+ (framework) como invariante que roda. `sprint-manager` foi auditado e está são (opera pelo workspace).
32
+
33
+ ---
34
+
35
+ ## [1.7.1] — 2026-07-22 — Correção: `project:check` em projetos consumidores
36
+
37
+ ### Corrigido
38
+ - **`forja project:check` num projeto consumidor auditava `node_modules/forjajs/dist/`** em vez do
39
+ projeto (raiz cravada em `__dirname/..`), reportando os arquivos obrigatórios como faltando (score
40
+ 0%) — o que travava o gate `implement` do `orchestrate`. Agora audita `process.cwd()` (propagado
41
+ pelo dispatcher desde a 1.6.2). Mesma classe do `spec-cli` (v1.6.2); o `check-standards` ficou de
42
+ fora. O `check:all` **não** é afetado (agrega health/smoke/release, não `project:check`).
43
+
44
+ ### Adicionado
45
+ - **Gate `consumer-project-check`** no `release:check`: planta um arquivo só no cwd e prova que
46
+ `project:check` audita o projeto do consumidor, não o pacote. Provado com dentes (reprova o bug).
47
+
48
+ ---
49
+
7
50
  ## [1.7.0] — 2026-07-22 — O motor de orquestração: o namesake executando
8
51
 
9
52
  O nome do framework sempre foi orquestração multiagente; até aqui, a topologia era coerente
@@ -433,6 +433,93 @@ const consumerSpecNew = {
433
433
  return { status: 'ok', detail: 'spec criada no projeto do consumidor; templates do pacote resolvem', fix: null };
434
434
  },
435
435
  };
436
+ /**
437
+ * A mesma classe do `consumer-spec-new`, na AUDITORIA: `project:check` cravava a raiz em
438
+ * `__dirname/..` e auditava o PACOTE (`node_modules/forjajs/dist`) em vez do projeto do consumidor —
439
+ * reportava tudo faltando, score 0% (bug da v1.7.0, que travou uma corrida do `orchestrate`). O gate
440
+ * planta um arquivo que SÓ existe no cwd e confere que o comando o enxerga. Se ele auditasse o pacote,
441
+ * o arquivo do cwd não apareceria.
442
+ */
443
+ const consumerProjectCheck = {
444
+ id: 'consumer-project-check',
445
+ title: 'project:check audita o projeto do consumidor (cwd), não o pacote',
446
+ severity: 'critical',
447
+ dependsOn: 'install',
448
+ probe(env) {
449
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
450
+ const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.forja;
451
+ const bin = path.join(env.pkgDir, binRel);
452
+ // Um AGENTS.md real, presente SÓ no cwd — a testemunha de qual raiz o comando auditou.
453
+ const marker = 'Marcador de auditoria do consumidor com mais de cem caracteres para não ser tratado como placeholder pelo check de padrões.\n';
454
+ env.fs.writeFileSync(path.join(env.installDir, 'AGENTS.md'), marker);
455
+ const res = env.spawn(process.execPath, [bin, 'project:check'], { cwd: env.installDir });
456
+ const saida = `${res.stdout || ''}${res.stderr || ''}`;
457
+ // A linha do AGENTS.md: "OK ... AGENTS.md" (achou no cwd) vs "Faltando" (auditou o pacote).
458
+ const linha = saida.split('\n').find((l) => /\bAGENTS\.md\b/.test(l)) || '';
459
+ if (/Faltando/i.test(linha) || linha === '') {
460
+ return {
461
+ status: 'fail',
462
+ detail: 'project:check não enxergou o AGENTS.md do cwd — está auditando o pacote, não o projeto',
463
+ fix: 'a raiz auditada deve ser process.cwd(), não path.resolve(__dirname, ..) — ver check-standards',
464
+ };
465
+ }
466
+ return { status: 'ok', detail: 'project:check audita o cwd (o AGENTS.md do consumidor foi visto)', fix: null };
467
+ },
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
+ };
436
523
  /** @type {import('./checks.ts').Check[]} */
437
524
  export const RELEASE_CHECKS = [
438
525
  treeClean,
@@ -440,6 +527,8 @@ export const RELEASE_CHECKS = [
440
527
  registryScripts,
441
528
  smokeCommands,
442
529
  consumerSpecNew,
530
+ consumerProjectCheck,
531
+ consumerProjectSurfaces,
443
532
  importsResolve,
444
533
  depsDeclared,
445
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({
@@ -1,10 +1,11 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
- import { fileURLToPath } from 'node:url';
4
3
  import { resolveProject, getWorkspaceInfo, initWorkspace } from "../lib/workspace.js";
5
- const __filename = fileURLToPath(import.meta.url);
6
- const __dirname = path.dirname(__filename);
7
- const root = path.resolve(__dirname, '..');
4
+ // O projeto a auditar é ONDE O USUÁRIO INVOCOU — `process.cwd()`, propagado pelo dispatcher desde a
5
+ // v1.6.2. Cravar `__dirname/..` auditava a raiz do PACOTE (`node_modules/forjajs/dist`) no consumidor
6
+ // e reportava tudo como faltando (bug da v1.7.0, mesma classe do spec-cli). No repo do framework,
7
+ // invoca-se da raiz, então cwd = a raiz do framework — comportamento inalterado.
8
+ const root = process.cwd();
8
9
  const [projectArg] = process.argv.slice(2);
9
10
  const project = projectArg || 'framework-root';
10
11
  let projectDir;
@@ -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)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.7.0",
3
+ "version": "1.7.2",
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",