forjajs 1.3.2 → 1.6.0

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.
Files changed (51) hide show
  1. package/AGENTS.md +5 -0
  2. package/CHANGELOG.md +74 -0
  3. package/README.en.md +1 -0
  4. package/README.md +11 -4
  5. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
  6. package/dist/lib/agent-topology.d.ts +38 -0
  7. package/dist/lib/agent-topology.js +65 -0
  8. package/dist/lib/code-context.d.ts +41 -0
  9. package/dist/lib/code-context.js +108 -0
  10. package/dist/lib/core/doc-graph.d.ts +13 -0
  11. package/dist/lib/core/doc-graph.js +47 -0
  12. package/dist/lib/core/gates.d.ts +36 -0
  13. package/dist/lib/core/gates.js +35 -0
  14. package/dist/lib/core/health.js +64 -1
  15. package/dist/lib/core/project-smoke.d.ts +46 -0
  16. package/dist/lib/core/project-smoke.js +248 -0
  17. package/dist/lib/core/registry.d.ts +30 -0
  18. package/dist/lib/core/registry.js +30 -0
  19. package/dist/lib/core/release.d.ts +30 -0
  20. package/dist/lib/generators/memory-generator.d.ts +1 -0
  21. package/dist/lib/generators/memory-generator.js +44 -0
  22. package/dist/lib/generators/readme-generator.js +1 -0
  23. package/dist/lib/memory-audit.d.ts +31 -0
  24. package/dist/lib/memory-audit.js +81 -0
  25. package/dist/lib/project-upgrade.d.ts +28 -0
  26. package/dist/lib/project-upgrade.js +74 -0
  27. package/dist/scripts/agent-router.js +1 -1
  28. package/dist/scripts/code-context.d.ts +12 -0
  29. package/dist/scripts/code-context.js +73 -0
  30. package/dist/scripts/gates.d.ts +10 -0
  31. package/dist/scripts/gates.js +44 -0
  32. package/dist/scripts/memory-audit.d.ts +11 -0
  33. package/dist/scripts/memory-audit.js +49 -0
  34. package/dist/scripts/project-smoke.d.ts +14 -0
  35. package/dist/scripts/project-smoke.js +44 -0
  36. package/dist/scripts/project-upgrade.d.ts +11 -0
  37. package/dist/scripts/project-upgrade.js +61 -0
  38. package/dist/scripts/token-economy.d.ts +20 -0
  39. package/dist/scripts/token-economy.js +140 -0
  40. package/memory/90-decisions/0025-coerencia-da-documentacao.md +10 -0
  41. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
  42. package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
  43. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
  44. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
  45. package/package.json +1 -1
  46. package/specs/code-context/spec.md +56 -0
  47. package/specs/gates/spec.md +63 -0
  48. package/specs/memory-audit/spec.md +54 -0
  49. package/specs/orchestration-coherent/spec.md +95 -0
  50. package/specs/project-smoke/spec.md +96 -0
  51. package/specs/project-upgrade/spec.md +58 -0
@@ -38,7 +38,8 @@ import { fileURLToPath } from 'node:url';
38
38
  import { getWorkspaceDbPath, getWorkspaceInfo } from "../workspace.js";
39
39
  import { runChecks as run, worstStatus, stripTemplateLiterals, asErrno } from "./checks.js";
40
40
  import { COMMANDS } from "./registry.js";
41
- import { scanCommands, scanLinks, projectCommands } from "./doc-graph.js";
41
+ import { scanCommands, scanLinks, projectCommands, scanAdrRefs, adrNumbers } from "./doc-graph.js";
42
+ import { topologyIssues } from "../agent-topology.js";
42
43
  /** @typedef {import('./checks.ts').Status} Status */
43
44
  // O runner vive em checks.mjs e é compartilhado com o catálogo de release (SPEC-010). Re-exportado
44
45
  // aqui para que `tools:doctor` e o hook SessionStart sigam importando de um lugar só.
@@ -495,6 +496,66 @@ const docsLinks = {
495
496
  return { status: 'ok', detail: 'todo link relativo resolve', fix: null };
496
497
  },
497
498
  };
499
+ /**
500
+ * Referência a decisão que não existe é trilha que apodrece. Uma spec ou doc cita `ADR-0026`, o ADR
501
+ * nunca foi escrito (ou foi renumerado), e o paper trail mente em silêncio. `warn`, não `critical`:
502
+ * confunde o registro, não impede o framework de trabalhar — mesma família de `docs-links`.
503
+ */
504
+ const adrRefs = {
505
+ id: 'adr-refs',
506
+ title: 'toda citação ADR-NNNN aponta para um ADR existente',
507
+ severity: 'warn',
508
+ scope: 'repo',
509
+ probe(env) {
510
+ if (!isFrameworkRepo(env)) {
511
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
512
+ }
513
+ const existing = adrNumbers(env);
514
+ const dangling = scanAdrRefs(env).filter((r) => !existing.has(r.num));
515
+ if (dangling.length) {
516
+ const amostra = dangling.slice(0, 5).map((d) => `${d.ref} (${d.file}:${d.line})`).join(', ');
517
+ return {
518
+ status: 'warn',
519
+ detail: `${dangling.length} citação(ões) de ADR inexistente: ${amostra}`,
520
+ fix: 'escreva o ADR referenciado ou corrija o número no arquivo:linha indicado',
521
+ };
522
+ }
523
+ return { status: 'ok', detail: `toda referência a ADR resolve (${existing.size} ADRs)`, fix: null };
524
+ },
525
+ };
526
+ /**
527
+ * A topologia de orquestração é descrita em três lugares (router, `.claude/agents`, `AGENTS.md`) e
528
+ * pode divergir em silêncio (SPEC-019): um sub-agent que o router não roteia, um papel roteável sem
529
+ * executor, um agente não documentado. É a coerência da orquestração — o namesake do framework —
530
+ * feita invariante. `warn`: confunde a topologia, não trava o núcleo. Mesma família de `adr-refs`.
531
+ */
532
+ const agentTopology = {
533
+ id: 'agent-topology',
534
+ title: 'a topologia de agentes concorda entre router, .claude/agents e AGENTS.md',
535
+ severity: 'warn',
536
+ scope: 'repo',
537
+ probe(env) {
538
+ if (!isFrameworkRepo(env)) {
539
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
540
+ }
541
+ const { unrouted, missingExecutor, undocumented } = topologyIssues({ fs: env.fs, root: env.root });
542
+ const problemas = [];
543
+ if (unrouted.length)
544
+ problemas.push(`sem rota no router: ${unrouted.join(', ')}`);
545
+ if (missingExecutor.length)
546
+ problemas.push(`roteável sem .claude/agent: ${missingExecutor.join(', ')}`);
547
+ if (undocumented.length)
548
+ problemas.push(`não documentado no AGENTS.md: ${undocumented.join(', ')}`);
549
+ if (problemas.length) {
550
+ return {
551
+ status: 'warn',
552
+ detail: `topologia incoerente — ${problemas.join('; ')}`,
553
+ fix: 'alinhe VALID_AGENTS (agent-router.ts), .claude/agents/ e AGENTS.md',
554
+ };
555
+ }
556
+ return { status: 'ok', detail: 'router, .claude/agents e AGENTS.md concordam', fix: null };
557
+ },
558
+ };
498
559
  /** @type {Check[]} */
499
560
  export const CHECKS = [
500
561
  nativeAbi,
@@ -507,6 +568,8 @@ export const CHECKS = [
507
568
  docsCommands,
508
569
  commandsDocumented,
509
570
  docsLinks,
571
+ adrRefs,
572
+ agentTopology,
510
573
  ];
511
574
  /**
512
575
  * Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
@@ -0,0 +1,46 @@
1
+ /**
2
+ * lib/core/project-smoke.ts — o gate do projeto gerado.
3
+ *
4
+ * Guarda a fronteira que `release:check` não vê, um nível acima: **o gerador mente sobre o projeto**.
5
+ * O `release:check` prova que o pacote `forjajs` instala e roda. Este prova que o que ele *gera*
6
+ * — via `create-memory-nest-kit` — é coerente e buildar. É a mesma classe da SPEC-010, na saída.
7
+ *
8
+ * O gerador escreve a partir de templates. Cada substituição é uma chance de mentira silenciosa: um
9
+ * `{{FEATURE}}` que vaza, um `package.json` que não parseia, uma estrutura de memória incompleta. O
10
+ * princípio é o mesmo do release: **grep não prova ausência; gerar e inspecionar prova.**
11
+ *
12
+ * O runner é o de `checks.ts`, o mesmo do doctor e do release. Uma máquina, três fronteiras.
13
+ */
14
+ import fs from 'node:fs';
15
+ import { worstStatus } from './checks.ts';
16
+ import type { Check } from './checks.ts';
17
+ export { worstStatus };
18
+ interface SmokeEnv {
19
+ root: string;
20
+ fs: typeof fs;
21
+ projectDir?: string;
22
+ full: boolean;
23
+ spawn: (cmd: string, args: string[], opts?: any) => {
24
+ stdout: string;
25
+ stderr: string;
26
+ code: number;
27
+ };
28
+ }
29
+ /**
30
+ * Gera um projeto num diretório temporário isolado e entrega o caminho ao callback. Limpa o
31
+ * temporário **sempre**, inclusive quando o callback lança — o mesmo contrato do `withCleanInstall`.
32
+ */
33
+ export declare function withGeneratedProject<T>(fn: (ctx: {
34
+ projectDir: string;
35
+ }) => Promise<T> | T, { root, spawn }: {
36
+ root?: string;
37
+ spawn: SmokeEnv['spawn'];
38
+ }): Promise<T>;
39
+ /** @type {Check[]} */
40
+ export declare const SMOKE_CHECKS: Check[];
41
+ export declare function defaultEnv(overrides?: Partial<SmokeEnv>): SmokeEnv;
42
+ /** Gera um projeto isolado, roda os checks, limpa. */
43
+ export declare function runProjectSmoke({ full, env: overrides }?: {
44
+ full?: boolean;
45
+ env?: Partial<SmokeEnv>;
46
+ }): Promise<import("./checks.ts").Result[]>;
@@ -0,0 +1,248 @@
1
+ /**
2
+ * lib/core/project-smoke.ts — o gate do projeto gerado.
3
+ *
4
+ * Guarda a fronteira que `release:check` não vê, um nível acima: **o gerador mente sobre o projeto**.
5
+ * O `release:check` prova que o pacote `forjajs` instala e roda. Este prova que o que ele *gera*
6
+ * — via `create-memory-nest-kit` — é coerente e buildar. É a mesma classe da SPEC-010, na saída.
7
+ *
8
+ * O gerador escreve a partir de templates. Cada substituição é uma chance de mentira silenciosa: um
9
+ * `{{FEATURE}}` que vaza, um `package.json` que não parseia, uma estrutura de memória incompleta. O
10
+ * princípio é o mesmo do release: **grep não prova ausência; gerar e inspecionar prova.**
11
+ *
12
+ * O runner é o de `checks.ts`, o mesmo do doctor e do release. Uma máquina, três fronteiras.
13
+ */
14
+ import { execFileSync } from 'node:child_process';
15
+ import fs from 'node:fs';
16
+ import os from 'node:os';
17
+ import path from 'node:path';
18
+ import { fileURLToPath } from 'node:url';
19
+ import { runChecks as run, worstStatus } from "./checks.js";
20
+ // @ts-ignore — validador legado sem tipos exportados; usado só pela forma { isValid, errors }.
21
+ import { validateProjectStructure } from "../validators/structure-validator.js";
22
+ export { worstStatus };
23
+ const __filename = fileURLToPath(import.meta.url);
24
+ const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
25
+ /** Placeholders do gerador: identificadores MAIÚSCULOS entre chaves duplas (`{{FEATURE}}`). */
26
+ const PLACEHOLDER_RE = /\{\{[A-Z][A-Z0-9_]*\}\}/;
27
+ /**
28
+ * Gera um projeto num diretório temporário isolado e entrega o caminho ao callback. Limpa o
29
+ * temporário **sempre**, inclusive quando o callback lança — o mesmo contrato do `withCleanInstall`.
30
+ */
31
+ export async function withGeneratedProject(fn, { root = repoRoot, spawn }) {
32
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-smoke-'));
33
+ const projectDir = path.join(dir, 'smoke-proj');
34
+ try {
35
+ const gen = path.join(root, 'bin', 'create-memory-nest-kit.ts');
36
+ const res = spawn(process.execPath, [gen, projectDir, '--force'], { cwd: dir });
37
+ if (res.code !== 0) {
38
+ throw new Error(`o gerador saiu com código ${res.code}:\n${(res.stderr || res.stdout).slice(0, 800)}`);
39
+ }
40
+ return await fn({ projectDir });
41
+ }
42
+ finally {
43
+ fs.rmSync(dir, { recursive: true, force: true });
44
+ }
45
+ }
46
+ // ---------------------------------------------------------------------------
47
+ // Walk — arquivos de texto do projeto, menos node_modules
48
+ // ---------------------------------------------------------------------------
49
+ function walkFiles(env, dir, out) {
50
+ let entries;
51
+ try {
52
+ entries = env.fs.readdirSync(dir);
53
+ }
54
+ catch {
55
+ return out;
56
+ }
57
+ for (const entry of entries) {
58
+ if (entry === 'node_modules' || entry === '.git')
59
+ continue;
60
+ const p = path.join(dir, entry);
61
+ let st;
62
+ try {
63
+ st = env.fs.statSync(p);
64
+ }
65
+ catch {
66
+ continue;
67
+ }
68
+ if (st.isDirectory())
69
+ walkFiles(env, p, out);
70
+ else
71
+ out.push(p);
72
+ }
73
+ return out;
74
+ }
75
+ /** Lê como texto; devolve null para binário/ilegível (não é competência deste gate). */
76
+ function readText(env, file) {
77
+ try {
78
+ const buf = env.fs.readFileSync(file);
79
+ if (buf.includes(0))
80
+ return null; // binário
81
+ return buf.toString('utf8');
82
+ }
83
+ catch {
84
+ return null;
85
+ }
86
+ }
87
+ // ---------------------------------------------------------------------------
88
+ // Checks
89
+ // ---------------------------------------------------------------------------
90
+ /** Se o projeto não nasceu, todo o resto é irrelevante — daí os outros dependerem deste. */
91
+ const generated = {
92
+ id: 'generated',
93
+ title: 'o gerador produz um projeto',
94
+ severity: 'critical',
95
+ probe(env) {
96
+ const marker = path.join(env.projectDir, 'AGENTS.md');
97
+ return env.fs.existsSync(marker)
98
+ ? { status: 'ok', detail: `projeto gerado em ${path.basename(env.projectDir)}`, fix: null }
99
+ : { status: 'fail', detail: 'o gerador rodou mas não produziu AGENTS.md', fix: 'investigue create-memory-nest-kit' };
100
+ },
101
+ };
102
+ /** O bug mais barato de introduzir e o mais visível ao usuário: um template não substituído. */
103
+ const noPlaceholders = {
104
+ id: 'no-placeholders',
105
+ title: 'nenhum placeholder {{...}} vazou',
106
+ severity: 'critical',
107
+ dependsOn: 'generated',
108
+ probe(env) {
109
+ const leaked = [];
110
+ for (const file of walkFiles(env, env.projectDir, [])) {
111
+ const src = readText(env, file);
112
+ if (src == null)
113
+ continue;
114
+ const m = src.match(PLACEHOLDER_RE);
115
+ if (m)
116
+ leaked.push(`${path.relative(env.projectDir, file)} → ${m[0]}`);
117
+ }
118
+ if (leaked.length) {
119
+ return {
120
+ status: 'fail',
121
+ detail: `${leaked.length} placeholder(s) não substituído(s): ${leaked.slice(0, 3).join('; ')}`,
122
+ fix: 'o gerador esqueceu um replace — confira o fillTemplate do gerador correspondente',
123
+ };
124
+ }
125
+ return { status: 'ok', detail: 'todo template foi substituído', fix: null };
126
+ },
127
+ };
128
+ /** `package.json` gerado que não parseia entrega um projeto morto no `npm install`. */
129
+ const jsonValid = {
130
+ id: 'json-valid',
131
+ title: 'todo package.json gerado é JSON válido',
132
+ severity: 'critical',
133
+ dependsOn: 'generated',
134
+ probe(env) {
135
+ const broken = [];
136
+ let total = 0;
137
+ for (const file of walkFiles(env, env.projectDir, [])) {
138
+ if (path.basename(file) !== 'package.json')
139
+ continue;
140
+ total += 1;
141
+ const src = readText(env, file);
142
+ try {
143
+ JSON.parse(src ?? '');
144
+ }
145
+ catch (e) {
146
+ broken.push(`${path.relative(env.projectDir, file)}: ${e.message}`);
147
+ }
148
+ }
149
+ if (broken.length) {
150
+ return { status: 'fail', detail: `package.json inválido: ${broken.join('; ')}`, fix: 'corrija o template do package.json no gerador' };
151
+ }
152
+ return { status: 'ok', detail: `${total} package.json válido(s)`, fix: null };
153
+ },
154
+ };
155
+ /** Reusa o validador que o próprio gerador roda no fim — uma máquina, não duas (SPEC-009). */
156
+ const structure = {
157
+ id: 'structure',
158
+ title: 'a estrutura do projeto gerado é íntegra',
159
+ severity: 'critical',
160
+ dependsOn: 'generated',
161
+ probe(env) {
162
+ const report = validateProjectStructure(env.projectDir, { includeNest: true });
163
+ if (!report.isValid) {
164
+ return {
165
+ status: 'fail',
166
+ detail: `${report.errors.length} problema(s): ${report.errors.slice(0, 3).join('; ')}`,
167
+ fix: 'um arquivo/diretório crítico não foi gerado — confira o gerador de estrutura',
168
+ };
169
+ }
170
+ return { status: 'ok', detail: 'estrutura de memória e backend completas', fix: null };
171
+ },
172
+ };
173
+ /**
174
+ * O projeto gerado **herda o gate** dos mapas (ADR-0030): `scripts/check-memory-maps.mjs` viaja com
175
+ * ele. Sem isso, a coerência mapa↔código do usuário volta a viver por disciplina. Este check prova
176
+ * que a propagação aconteceu — o framework não só tem gates, ele os transmite.
177
+ */
178
+ const gateInherited = {
179
+ id: 'gate-inherited',
180
+ title: 'o projeto gerado carrega o gate dos mapas (ADR-0030)',
181
+ severity: 'critical',
182
+ dependsOn: 'generated',
183
+ probe(env) {
184
+ const gate = path.join(env.projectDir, 'scripts', 'check-memory-maps.mjs');
185
+ return env.fs.existsSync(gate)
186
+ ? { status: 'ok', detail: 'scripts/check-memory-maps.mjs presente — o invariante viaja com o projeto', fix: null }
187
+ : { status: 'fail', detail: 'o projeto gerado não trouxe o gate dos mapas', fix: 'confira o scriptTemplates do memory-generator' };
188
+ },
189
+ };
190
+ /**
191
+ * A prova final, e a mais cara: o backend gerado **buildar de verdade**. Só no tier `--full` —
192
+ * `npm install` de um projeto NestJS é lento e usa rede, então roda antes de release, não a cada
193
+ * commit. É o análogo do clean-install do `release:check`, na saída do gerador.
194
+ */
195
+ const builds = {
196
+ id: 'builds',
197
+ title: 'o backend gerado instala e buildar (--full)',
198
+ severity: 'critical',
199
+ dependsOn: 'structure',
200
+ probe(env) {
201
+ if (!env.full) {
202
+ return { status: 'skipped', detail: 'tier --full desligado (custo de rede); rode com --full antes de publicar', fix: null };
203
+ }
204
+ const backend = path.join(env.projectDir, 'backend');
205
+ if (!env.fs.existsSync(path.join(backend, 'package.json'))) {
206
+ return { status: 'skipped', detail: 'sem backend/ (projeto só-memória)', fix: null };
207
+ }
208
+ const install = env.spawn('npm', ['install', '--no-audit', '--no-fund'], { cwd: backend });
209
+ if (install.code !== 0) {
210
+ return { status: 'fail', detail: `npm install falhou no backend gerado:\n${(install.stderr || install.stdout).slice(0, 500)}`, fix: 'confira as dependências no template do package.json' };
211
+ }
212
+ const build = env.spawn('npm', ['run', 'build'], { cwd: backend });
213
+ if (build.code !== 0) {
214
+ return { status: 'fail', detail: `npm run build falhou no backend gerado:\n${(build.stderr || build.stdout).slice(0, 500)}`, fix: 'o código gerado não compila — confira os templates do nest-generator' };
215
+ }
216
+ return { status: 'ok', detail: 'backend gerado instala e compila', fix: null };
217
+ },
218
+ };
219
+ /** @type {Check[]} */
220
+ export const SMOKE_CHECKS = [generated, noPlaceholders, jsonValid, structure, gateInherited, builds];
221
+ export function defaultEnv(overrides = {}) {
222
+ return {
223
+ root: repoRoot,
224
+ fs,
225
+ full: false,
226
+ spawn: (cmd, args, opts) => {
227
+ // Isolamento como no release: sem NODE_PATH nem npm_config_* herdados vazando para o install.
228
+ const env = { ...process.env };
229
+ delete env.NODE_PATH;
230
+ for (const key of Object.keys(env))
231
+ if (key.startsWith('npm_'))
232
+ delete env[key];
233
+ try {
234
+ return { stdout: execFileSync(cmd, args, { encoding: 'utf8', stdio: 'pipe', env, ...opts }), stderr: '', code: 0 };
235
+ }
236
+ catch (err) {
237
+ const e = err;
238
+ return { stdout: e.stdout || '', stderr: e.stderr || String(err), code: e.status ?? 1 };
239
+ }
240
+ },
241
+ ...overrides,
242
+ };
243
+ }
244
+ /** Gera um projeto isolado, roda os checks, limpa. */
245
+ export async function runProjectSmoke({ full = false, env: overrides = {} } = {}) {
246
+ const base = defaultEnv({ full, ...overrides });
247
+ return withGeneratedProject(({ projectDir }) => run({ checks: SMOKE_CHECKS, env: { ...base, projectDir } }), { root: base.root, spawn: base.spawn });
248
+ }
@@ -54,6 +54,11 @@ export declare const COMMANDS: {
54
54
  node: string;
55
55
  args: string[];
56
56
  };
57
+ 'project:upgrade': {
58
+ domain: string;
59
+ desc: string;
60
+ node: string;
61
+ };
57
62
  'workspace:project:check': {
58
63
  domain: string;
59
64
  desc: string;
@@ -156,6 +161,11 @@ export declare const COMMANDS: {
156
161
  node: string;
157
162
  args: string[];
158
163
  };
164
+ 'code:context': {
165
+ domain: string;
166
+ desc: string;
167
+ node: string;
168
+ };
159
169
  'code:index': {
160
170
  domain: string;
161
171
  desc: string;
@@ -212,6 +222,11 @@ export declare const COMMANDS: {
212
222
  desc: string;
213
223
  node: string;
214
224
  };
225
+ 'memory:audit': {
226
+ domain: string;
227
+ desc: string;
228
+ node: string;
229
+ };
215
230
  'context:smart': {
216
231
  domain: string;
217
232
  desc: string;
@@ -253,6 +268,11 @@ export declare const COMMANDS: {
253
268
  desc: string;
254
269
  node: string;
255
270
  };
271
+ 'token:economy': {
272
+ domain: string;
273
+ desc: string;
274
+ node: string;
275
+ };
256
276
  'project:check': {
257
277
  domain: string;
258
278
  desc: string;
@@ -268,6 +288,16 @@ export declare const COMMANDS: {
268
288
  desc: string;
269
289
  node: string;
270
290
  };
291
+ 'project:smoke': {
292
+ domain: string;
293
+ desc: string;
294
+ node: string;
295
+ };
296
+ 'check:all': {
297
+ domain: string;
298
+ desc: string;
299
+ node: string;
300
+ };
271
301
  'project:dashboard': {
272
302
  domain: string;
273
303
  desc: string;
@@ -67,6 +67,11 @@ export const COMMANDS = {
67
67
  node: 'scripts/agent-harness.ts',
68
68
  args: ['project:list'],
69
69
  },
70
+ 'project:upgrade': {
71
+ domain: 'workspace',
72
+ desc: 'Traz peças novas de scaffold para um projeto gerado — aditivo (SPEC-018). --apply para copiar',
73
+ node: 'scripts/project-upgrade.ts',
74
+ },
70
75
  'workspace:project:check': {
71
76
  domain: 'workspace',
72
77
  desc: 'Valida padrões em um projeto do workspace',
@@ -173,6 +178,11 @@ export const COMMANDS = {
173
178
  node: 'scripts/agent-harness.ts',
174
179
  args: ['code:impact'],
175
180
  },
181
+ 'code:context': {
182
+ domain: 'code',
183
+ desc: 'Pacote de contexto mínimo de um domínio: o mapa (context.md), + código com --code (ADR-0009)',
184
+ node: 'scripts/code-context.ts',
185
+ },
176
186
  'code:index': {
177
187
  domain: 'code',
178
188
  desc: 'Inicializa índice codegraph',
@@ -230,6 +240,11 @@ export const COMMANDS = {
230
240
  desc: 'Extrai conhecimento global da memória',
231
241
  node: 'scripts/extract-global-knowledge.ts',
232
242
  },
243
+ 'memory:audit': {
244
+ domain: 'memoria',
245
+ desc: 'Coerência mapa↔código: mapa não cita código morto (falha) + módulo sem mapa (aviso). SPEC-017',
246
+ node: 'scripts/memory-audit.ts',
247
+ },
233
248
  // --- Contexto & token economy ---------------------------------------------
234
249
  'context:smart': {
235
250
  domain: 'contexto',
@@ -272,6 +287,11 @@ export const COMMANDS = {
272
287
  desc: 'Benchmark de consumo de tokens',
273
288
  node: 'scripts/token-benchmark.ts',
274
289
  },
290
+ 'token:economy': {
291
+ domain: 'contexto',
292
+ desc: 'Economia de token: eixos arquitetura + memória; --project mede seus domínios reais (ADR-0009/0027)',
293
+ node: 'scripts/token-economy.ts',
294
+ },
275
295
  // --- Governança & qualidade ---------------------------------------------------
276
296
  'project:check': {
277
297
  domain: 'governanca',
@@ -288,6 +308,16 @@ export const COMMANDS = {
288
308
  desc: 'Gate do tarball: instala limpo e prova que o pacote funciona (ADR-0024). --publish para o modo estrito',
289
309
  node: 'scripts/release-check.ts',
290
310
  },
311
+ 'project:smoke': {
312
+ domain: 'governanca',
313
+ desc: 'Gate do projeto gerado: gera isolado e prova que é coerente (SPEC-015). --full instala e builda o backend',
314
+ node: 'scripts/project-smoke.ts',
315
+ },
316
+ 'check:all': {
317
+ domain: 'governanca',
318
+ desc: 'Roda a bateria inteira de gates e dá um veredito (SPEC-020). --full inclui tarball e build',
319
+ node: 'scripts/gates.ts',
320
+ },
291
321
  'project:dashboard': {
292
322
  domain: 'governanca',
293
323
  desc: 'Gera dashboard estático de status',
@@ -62,6 +62,11 @@ export declare function defaultEnv(overrides?: {}): {
62
62
  node: string;
63
63
  args: string[];
64
64
  };
65
+ 'project:upgrade': {
66
+ domain: string;
67
+ desc: string;
68
+ node: string;
69
+ };
65
70
  'workspace:project:check': {
66
71
  domain: string;
67
72
  desc: string;
@@ -164,6 +169,11 @@ export declare function defaultEnv(overrides?: {}): {
164
169
  node: string;
165
170
  args: string[];
166
171
  };
172
+ 'code:context': {
173
+ domain: string;
174
+ desc: string;
175
+ node: string;
176
+ };
167
177
  'code:index': {
168
178
  domain: string;
169
179
  desc: string;
@@ -220,6 +230,11 @@ export declare function defaultEnv(overrides?: {}): {
220
230
  desc: string;
221
231
  node: string;
222
232
  };
233
+ 'memory:audit': {
234
+ domain: string;
235
+ desc: string;
236
+ node: string;
237
+ };
223
238
  'context:smart': {
224
239
  domain: string;
225
240
  desc: string;
@@ -261,6 +276,11 @@ export declare function defaultEnv(overrides?: {}): {
261
276
  desc: string;
262
277
  node: string;
263
278
  };
279
+ 'token:economy': {
280
+ domain: string;
281
+ desc: string;
282
+ node: string;
283
+ };
264
284
  'project:check': {
265
285
  domain: string;
266
286
  desc: string;
@@ -276,6 +296,16 @@ export declare function defaultEnv(overrides?: {}): {
276
296
  desc: string;
277
297
  node: string;
278
298
  };
299
+ 'project:smoke': {
300
+ domain: string;
301
+ desc: string;
302
+ node: string;
303
+ };
304
+ 'check:all': {
305
+ domain: string;
306
+ desc: string;
307
+ node: string;
308
+ };
279
309
  'project:dashboard': {
280
310
  domain: string;
281
311
  desc: string;
@@ -8,6 +8,7 @@
8
8
  export declare function getAllMemoryTemplates(): {
9
9
  'scripts/build-context-pack.mjs': string;
10
10
  'scripts/append-handoff.mjs': string;
11
+ 'scripts/check-memory-maps.mjs': string;
11
12
  'scripts/lib/skill-loader.mjs': string;
12
13
  'scripts/memory-vacuum.mjs': string;
13
14
  'scripts/memory-watcher.mjs': string;
@@ -634,6 +634,50 @@ const template = '# Handoff: ' + from + ' -> ' + to + '\\n\\n'
634
634
 
635
635
  fs.writeFileSync(file, template, 'utf8');
636
636
  console.log('Handoff criado: ' + file);
637
+ `,
638
+ 'scripts/check-memory-maps.mjs': `import fs from 'node:fs';
639
+ import path from 'node:path';
640
+ import { fileURLToPath } from 'node:url';
641
+
642
+ // Gate herdado do Forja (ADR-0030): os mapas de memoria (context.md) nao mentem sobre o codigo.
643
+ // Self-contained, zero dependencia. Rode no CI: node scripts/check-memory-maps.mjs
644
+ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
645
+ const domainsDir = path.join(root, 'memory/30-domains');
646
+ const modulesDir = path.join(root, 'backend/src/modules');
647
+ const BT = String.fromCharCode(96);
648
+ const CODE_REF = new RegExp(BT + '([a-z][a-zA-Z0-9/._-]*/[a-zA-Z0-9/._-]*[.]ts)' + BT, 'g');
649
+
650
+ function dirs(p) {
651
+ try { return fs.readdirSync(p).filter((e) => fs.statSync(path.join(p, e)).isDirectory()); }
652
+ catch { return []; }
653
+ }
654
+ function resolves(domain, ref) {
655
+ const bases = [path.join(modulesDir, domain), path.join(root, 'backend'), root];
656
+ return bases.some((b) => fs.existsSync(path.join(b, ref)));
657
+ }
658
+
659
+ let dangling = 0;
660
+ const domains = dirs(domainsDir);
661
+ for (const d of domains) {
662
+ let src;
663
+ try { src = fs.readFileSync(path.join(domainsDir, d, 'context.md'), 'utf8'); }
664
+ catch { continue; }
665
+ const refs = [...new Set([...src.matchAll(CODE_REF)].map((m) => m[1]))];
666
+ const bad = refs.filter((r) => !resolves(d, r));
667
+ if (bad.length) { dangling += bad.length; console.log('x ' + d + ': ' + bad.join(', ') + ' -- o mapa aponta, o arquivo nao existe'); }
668
+ else { console.log('ok ' + d + ' -- ' + refs.length + ' referencia(s)'); }
669
+ }
670
+ const mapped = new Set(domains);
671
+ for (const m of dirs(modulesDir)) {
672
+ if (!mapped.has(m)) console.log('! modulo ' + m + ' sem context.md -- economia de token perdida');
673
+ }
674
+ if (dangling) {
675
+ console.log('');
676
+ console.log('REPROVADO -- ' + dangling + ' referencia(s) pendurada(s). Corrija o context.md ou o path.');
677
+ process.exit(1);
678
+ }
679
+ console.log('');
680
+ console.log('OK -- os mapas de memoria batem com o codigo.');
637
681
  `,
638
682
  'scripts/lib/skill-loader.mjs': `import fs from 'node:fs';
639
683
  import path from 'node:path';
@@ -146,6 +146,7 @@ Mostra:
146
146
  | \`append-handoff.mjs\` | Cria novo arquivo de handoff |
147
147
  | \`memory-vacuum.mjs\` | Arquiva logs > 30 dias |
148
148
  | \`memory-watcher.mjs\` | Auto-sync de markdown → SQLite |
149
+ | \`check-memory-maps.mjs\` | Gate: os mapas (context.md) não citam código morto. Rode no CI |
149
150
 
150
151
  ## 📚 Documentação Importante
151
152
 
@@ -0,0 +1,31 @@
1
+ /**
2
+ * lib/memory-audit.ts — os mapas de memória não podem mentir sobre o código (SPEC-017, ADR-0009).
3
+ *
4
+ * A economia de token do Forja é o `context.md` como mapa (`token:economy` mede −61%). Mas um mapa
5
+ * que aponta "a regra mora em `domain/order.entity.ts`" **depois** que o arquivo foi renomeado é
6
+ * *pior* que mapa nenhum: engana com confiança, e um agente vai ler o lugar errado — pagando o custo
7
+ * e chegando à conclusão errada.
8
+ *
9
+ * Este módulo é o `adr-refs` dos mapas: extrai os paths de código que cada `context.md` cita e
10
+ * confere que eles existem. Referência pendurada num mapa é a economia de token se voltando contra si.
11
+ */
12
+ import fs from 'node:fs';
13
+ export interface AuditEnv {
14
+ fs: typeof fs;
15
+ }
16
+ export interface DomainAudit {
17
+ domain: string;
18
+ mapPath: string;
19
+ refs: number;
20
+ dangling: string[];
21
+ }
22
+ /** Módulos de código de um projeto: os diretórios sob `backend/src/modules/`. */
23
+ export declare function modulesOf(projectRoot: string, env?: AuditEnv): string[];
24
+ /**
25
+ * A direção reversa da coerência: módulo de código **sem** `context.md`. Não é uma mentira (o mapa
26
+ * não existe para mentir), mas é a economia de token perdida em silêncio — um domínio que cresceu e
27
+ * ninguém mapeou. `warn`, não `fail`.
28
+ */
29
+ export declare function modulesWithoutMap(projectRoot: string, env?: AuditEnv): string[];
30
+ /** Audita os mapas de todos os domínios de um projeto. */
31
+ export declare function auditMemoryMaps(projectRoot: string, env?: AuditEnv): DomainAudit[];