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 +43 -0
- package/dist/lib/core/release.js +89 -0
- package/dist/scripts/agent-harness.js +25 -14
- package/dist/scripts/check-standards.js +5 -4
- package/dist/scripts/context-ops.js +17 -12
- package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -0
- package/package.json +1 -1
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
|
package/dist/lib/core/release.js
CHANGED
|
@@ -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
|
-
|
|
73
|
-
|
|
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(
|
|
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(
|
|
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 ?
|
|
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: ${
|
|
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(
|
|
319
|
-
const runbook = path.join(
|
|
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) ?
|
|
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(
|
|
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:
|
|
349
|
+
detail: path.relative(projectRoot, runbook),
|
|
343
350
|
});
|
|
344
|
-
const specDir = path.join(
|
|
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
|
-
|
|
351
|
-
|
|
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
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
152
|
-
if (!file || !file.startsWith(
|
|
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(
|
|
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(
|
|
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(
|
|
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)
|