forjajs 4.0.1 → 4.1.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 (95) hide show
  1. package/CHANGELOG.md +111 -7
  2. package/DOC-MAP.md +1 -0
  3. package/README.md +7 -2
  4. package/dist/apps/cli/src/index.d.ts +18 -1
  5. package/dist/apps/cli/src/index.js +161 -26
  6. package/dist/apps/cli/src/params.d.ts +44 -0
  7. package/dist/apps/cli/src/params.js +123 -0
  8. package/dist/bin/forja.js +234 -13
  9. package/dist/bin/init-project.js +11 -62
  10. package/dist/lib/cli-output.d.ts +29 -0
  11. package/dist/lib/cli-output.js +39 -0
  12. package/dist/lib/core/checks.d.ts +1 -1
  13. package/dist/lib/core/health.d.ts +9 -0
  14. package/dist/lib/core/health.js +9 -0
  15. package/dist/lib/core/project-smoke.d.ts +6 -2
  16. package/dist/lib/core/project-smoke.js +83 -7
  17. package/dist/lib/core/registry.d.ts +38 -571
  18. package/dist/lib/core/registry.js +174 -25
  19. package/dist/lib/core/release.d.ts +1 -571
  20. package/dist/lib/core/release.js +0 -3
  21. package/dist/lib/handoffs-index.d.ts +16 -0
  22. package/dist/lib/handoffs-index.js +29 -0
  23. package/dist/lib/llm/claude-output.d.ts +8 -0
  24. package/dist/lib/llm/claude-output.js +54 -0
  25. package/dist/lib/llm/context.d.ts +22 -0
  26. package/dist/lib/llm/context.js +39 -0
  27. package/dist/lib/llm/session.d.ts +6 -1
  28. package/dist/lib/llm/session.js +12 -2
  29. package/dist/lib/multi-ai-instructions.d.ts +28 -0
  30. package/dist/lib/multi-ai-instructions.js +83 -0
  31. package/dist/lib/orchestrate.d.ts +5 -0
  32. package/dist/lib/orchestrate.js +18 -0
  33. package/dist/lib/specs-index.d.ts +20 -0
  34. package/dist/lib/specs-index.js +51 -0
  35. package/dist/lib/sprint-index.d.ts +15 -0
  36. package/dist/lib/sprint-index.js +34 -0
  37. package/dist/lib/status-model.d.ts +64 -0
  38. package/dist/lib/status-model.js +180 -0
  39. package/dist/packages/evals/src/index.d.ts +2 -0
  40. package/dist/packages/evals/src/index.js +21 -0
  41. package/dist/packages/llm/src/index.d.ts +24 -3
  42. package/dist/packages/llm/src/index.js +51 -5
  43. package/dist/scripts/cost-economy.js +12 -10
  44. package/dist/scripts/drift-check.d.ts +2 -0
  45. package/dist/scripts/drift-check.js +57 -1
  46. package/dist/scripts/engineer.js +7 -4
  47. package/dist/scripts/forja-setup.d.ts +14 -0
  48. package/dist/scripts/forja-setup.js +58 -0
  49. package/dist/scripts/forja-status.d.ts +11 -0
  50. package/dist/scripts/forja-status.js +70 -0
  51. package/dist/scripts/hook-session-start.js +20 -46
  52. package/dist/scripts/llm-fit.js +113 -8
  53. package/dist/scripts/project-smoke.js +13 -3
  54. package/dist/scripts/simulate.js +18 -6
  55. package/dist/scripts/token-economy.js +34 -28
  56. package/dist/scripts/tools-doctor.js +14 -6
  57. package/docs/2x/CLI-CAPABILITIES.md +34 -10
  58. package/docs/agent-operating-contract.md +1 -1
  59. package/docs/cli-first-operacao.md +17 -0
  60. package/docs/contrato-saida-cli.md +79 -0
  61. package/docs/llm-evolution.md +2 -1
  62. package/docs/llm-fit-loop.md +74 -2
  63. package/docs/publishing.md +0 -11
  64. package/docs/quick-reference.md +13 -0
  65. package/docs/roadmap-v4.1.md +199 -0
  66. package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
  67. package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
  68. package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
  69. package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
  70. package/package.json +4 -1
  71. package/specs/cli-intuitiva-v1/plan.md +169 -0
  72. package/specs/cli-intuitiva-v1/spec.md +163 -0
  73. package/specs/cli-intuitiva-v1/tasks.md +224 -0
  74. package/specs/contrato-saida-cli/plan.md +162 -0
  75. package/specs/contrato-saida-cli/spec.md +157 -0
  76. package/specs/contrato-saida-cli/tasks.md +153 -0
  77. package/specs/drift-sentinel/spec.md +17 -8
  78. package/specs/forja-status-caminho-feliz/plan.md +149 -0
  79. package/specs/forja-status-caminho-feliz/spec.md +158 -0
  80. package/specs/forja-status-caminho-feliz/tasks.md +175 -0
  81. package/specs/llm-adaptador-claude/plan.md +117 -0
  82. package/specs/llm-adaptador-claude/spec.md +144 -0
  83. package/specs/llm-adaptador-claude/tasks.md +100 -0
  84. package/specs/llm-benchmark-recomendacao/plan.md +121 -0
  85. package/specs/llm-benchmark-recomendacao/spec.md +141 -0
  86. package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
  87. package/specs/llm-contexto-e-sessoes/plan.md +143 -0
  88. package/specs/llm-contexto-e-sessoes/spec.md +139 -0
  89. package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
  90. package/specs/mcp-cobertura-nucleo/plan.md +158 -0
  91. package/specs/mcp-cobertura-nucleo/spec.md +161 -0
  92. package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
  93. package/specs/projeto-gerado-confiavel/plan.md +148 -0
  94. package/specs/projeto-gerado-confiavel/spec.md +142 -0
  95. package/specs/projeto-gerado-confiavel/tasks.md +139 -0
@@ -1,5 +1,27 @@
1
+ interface EngineerRun {
2
+ (argv: readonly string[]): {
3
+ code: number;
4
+ stdout: string;
5
+ stderr: string;
6
+ };
7
+ }
8
+ /**
9
+ * SPEC-048 — monta o bloco de contexto do façade `engineer` para o `llm:run --engineer`.
10
+ * Roda `forja engineer "<objetivo>" --json` (subprocesso; `run` injetável para teste), embute o
11
+ * relatório no prompt e devolve a **referência** (nunca o conteúdo é persistido).
12
+ *
13
+ * Exit ≠ 0 do façade → lança um `Error` com `.code = 'ENGINEER_FAILED'` e `.detail` = 1ª linha do
14
+ * stderr; o `llm:run` traduz isso em falha ANTES de chamar o provedor.
15
+ */
16
+ export declare function buildEngineerBlock(objective: string, opts?: {
17
+ run?: EngineerRun;
18
+ }): {
19
+ text: string;
20
+ ref: string;
21
+ };
1
22
  /** Resolve all inputs before launching a provider; hashes must cover the exact transmitted prompt. */
2
23
  export declare function buildContextPrompt(prompt: string, files: readonly string[], cwd?: string): {
3
24
  readonly prompt: string;
4
25
  readonly refs: readonly string[];
5
26
  };
27
+ export {};
@@ -1,5 +1,44 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
+ import { spawnSync } from 'node:child_process';
4
+ import { fileURLToPath } from 'node:url';
5
+ const forjaBin = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'forja.ts');
6
+ const defaultEngineerRun = (argv) => {
7
+ const result = spawnSync(process.execPath, [forjaBin, ...argv], { encoding: 'utf8', stdio: 'pipe' });
8
+ return { code: result.status ?? 1, stdout: result.stdout ?? '', stderr: [result.stderr ?? '', result.error?.message ?? ''].filter(Boolean).join('\n') };
9
+ };
10
+ /**
11
+ * SPEC-048 — monta o bloco de contexto do façade `engineer` para o `llm:run --engineer`.
12
+ * Roda `forja engineer "<objetivo>" --json` (subprocesso; `run` injetável para teste), embute o
13
+ * relatório no prompt e devolve a **referência** (nunca o conteúdo é persistido).
14
+ *
15
+ * Exit ≠ 0 do façade → lança um `Error` com `.code = 'ENGINEER_FAILED'` e `.detail` = 1ª linha do
16
+ * stderr; o `llm:run` traduz isso em falha ANTES de chamar o provedor.
17
+ */
18
+ export function buildEngineerBlock(objective, opts = {}) {
19
+ const run = opts.run ?? defaultEngineerRun;
20
+ const result = run(['engineer', objective, '--json']);
21
+ if (result.code !== 0) {
22
+ const error = new Error(`forja engineer falhou (exit ${result.code})`);
23
+ error.code = 'ENGINEER_FAILED';
24
+ error.detail = (result.stderr || result.stdout || '').trim().split('\n')[0] || `exit ${result.code}`;
25
+ throw error;
26
+ }
27
+ let report;
28
+ try {
29
+ report = JSON.parse(result.stdout);
30
+ }
31
+ catch {
32
+ const error = new Error('forja engineer --json não retornou JSON válido');
33
+ error.code = 'ENGINEER_FAILED';
34
+ error.detail = result.stdout.trim().slice(0, 200);
35
+ throw error;
36
+ }
37
+ return {
38
+ text: `=== Contexto do engineer (objetivo: ${objective}) ===\n${JSON.stringify(report)}`,
39
+ ref: `engineer:${objective}`,
40
+ };
41
+ }
3
42
  /** Resolve all inputs before launching a provider; hashes must cover the exact transmitted prompt. */
4
43
  export function buildContextPrompt(prompt, files, cwd = process.cwd()) {
5
44
  const refs = [...new Set(files.map((file) => path.resolve(cwd, file)))];
@@ -1,5 +1,6 @@
1
- import type { LlmProfile } from '../../packages/llm/src/index.ts';
1
+ import { RESUME_PROVIDERS, type LlmProfile } from '../../packages/llm/src/index.ts';
2
2
  import type { SqliteJsonRepository } from '../../packages/adapter-sqlite/src/index.ts';
3
+ export { RESUME_PROVIDERS };
3
4
  export interface LlmSession {
4
5
  readonly id: string;
5
6
  readonly cwd: string;
@@ -12,6 +13,10 @@ export declare class LlmSessionStore {
12
13
  private readonly repository;
13
14
  constructor(repository: SqliteJsonRepository);
14
15
  require(id: string, profile: LlmProfile, cwd: string): LlmSession;
16
+ /** Leitura pura para `llm:sessions` (SPEC-048): todas as sessões, mais recentes primeiro. */
17
+ all(): readonly LlmSession[];
18
+ /** Leitura pura: uma sessão pelo id, sem validar binding (que é do fluxo de retomada). */
19
+ find(id: string): LlmSession | undefined;
15
20
  save(id: string, profile: LlmProfile, cwd: string, observationId: string): void;
16
21
  private assertBinding;
17
22
  }
@@ -1,5 +1,7 @@
1
1
  import fs from 'node:fs';
2
2
  import { createHash } from 'node:crypto';
3
+ import { RESUME_PROVIDERS } from "../../packages/llm/src/index.js";
4
+ export { RESUME_PROVIDERS };
3
5
  export function profileFingerprint(profile) {
4
6
  return createHash('sha256').update(JSON.stringify({ provider: profile.provider, model: profile.model,
5
7
  command: profile.command, commandArgs: profile.commandArgs ?? [], privacy: profile.privacy })).digest('hex');
@@ -8,14 +10,22 @@ export class LlmSessionStore {
8
10
  repository;
9
11
  constructor(repository) { this.repository = repository; }
10
12
  require(id, profile, cwd) {
11
- if (profile.provider !== 'codex' || !validSessionId(id))
12
- throw new Error('Retomada exige Codex e ID explícito válido.');
13
+ if (!RESUME_PROVIDERS.has(profile.provider) || !validSessionId(id))
14
+ throw new Error('Retomada exige um adaptador que a suporte (codex, claude) e um ID explícito válido.');
13
15
  const session = this.repository.get('llm_session', id);
14
16
  if (!session)
15
17
  throw new Error('Sessão não registrada neste workspace Forja.');
16
18
  this.assertBinding(session, profile, cwd);
17
19
  return session;
18
20
  }
21
+ /** Leitura pura para `llm:sessions` (SPEC-048): todas as sessões, mais recentes primeiro. */
22
+ all() {
23
+ return [...this.repository.list('llm_session')].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
24
+ }
25
+ /** Leitura pura: uma sessão pelo id, sem validar binding (que é do fluxo de retomada). */
26
+ find(id) {
27
+ return this.repository.get('llm_session', id);
28
+ }
19
29
  save(id, profile, cwd, observationId) {
20
30
  if (!validSessionId(id))
21
31
  throw new Error('ID de sessão inválido retornado pelo provedor.');
@@ -0,0 +1,28 @@
1
+ /**
2
+ * lib/multi-ai-instructions.ts — as instruções nativas por IA de um projeto gerado (SPEC-047).
3
+ *
4
+ * Conteúdo canônico ÚNICO (ADR-0020): toda IA recebe a mesma explicação da estrutura Forja;
5
+ * só o cabeçalho muda. Extraído de `bin/init-project.ts step02CopyInstructions` para (a) ser
6
+ * chamável pelo smoke sem passar pelo `init-project.ts` (que não roda em dev), e (b) dar ao
7
+ * check de coerência (`project:smoke --ai`) a mesma fonte de verdade que a geração.
8
+ */
9
+ export declare const CANONICAL_INSTRUCTIONS = ".gemini-instructions.md";
10
+ export declare const AI_LABELS: Readonly<Record<string, string>>;
11
+ /**
12
+ * Remove as linhas de cabeçalho (as que diferem entre IAs) para comparar só o corpo.
13
+ * Usado pelo check `aiInstructionsCoherent`: dois `<ai>.md` da mesma geração devem ter corpo
14
+ * idêntico byte a byte depois disto.
15
+ */
16
+ export declare function stripInstructionHeader(text: string): string;
17
+ export interface WriteAiInstructionsResult {
18
+ readonly written: string[];
19
+ readonly skipped: string[];
20
+ }
21
+ /**
22
+ * Escreve `.ia-instructions/<ai>.md` (um por IA), `README.md` e `models.json` em `projectDir`,
23
+ * todos derivados de `<kitRoot>/.gemini-instructions.md`. `kitRoot` é a raiz do framework.
24
+ * Nunca lança por IA desconhecida — pula e reporta em `skipped`.
25
+ */
26
+ export declare function writeAiInstructions(projectDir: string, aiList: readonly string[], { kitRoot }: {
27
+ kitRoot: string;
28
+ }): WriteAiInstructionsResult;
@@ -0,0 +1,83 @@
1
+ /**
2
+ * lib/multi-ai-instructions.ts — as instruções nativas por IA de um projeto gerado (SPEC-047).
3
+ *
4
+ * Conteúdo canônico ÚNICO (ADR-0020): toda IA recebe a mesma explicação da estrutura Forja;
5
+ * só o cabeçalho muda. Extraído de `bin/init-project.ts step02CopyInstructions` para (a) ser
6
+ * chamável pelo smoke sem passar pelo `init-project.ts` (que não roda em dev), e (b) dar ao
7
+ * check de coerência (`project:smoke --ai`) a mesma fonte de verdade que a geração.
8
+ */
9
+ import fs from 'node:fs';
10
+ import path from 'node:path';
11
+ export const CANONICAL_INSTRUCTIONS = '.gemini-instructions.md';
12
+ export const AI_LABELS = {
13
+ copilot: 'GitHub Copilot',
14
+ claude: 'Claude',
15
+ gemini: 'Gemini',
16
+ codex: 'OpenAI Codex',
17
+ };
18
+ /** Linhas de cabeçalho que `writeAiInstructions` reescreve por IA — antes e depois. */
19
+ const HEADER_LINE_RES = [
20
+ /^# Instruções para .+ — Forja$/,
21
+ /^> Guia para .+ multi-IA por design\.$/,
22
+ ];
23
+ /**
24
+ * Remove as linhas de cabeçalho (as que diferem entre IAs) para comparar só o corpo.
25
+ * Usado pelo check `aiInstructionsCoherent`: dois `<ai>.md` da mesma geração devem ter corpo
26
+ * idêntico byte a byte depois disto.
27
+ */
28
+ export function stripInstructionHeader(text) {
29
+ return text
30
+ .split('\n')
31
+ .filter((line) => !HEADER_LINE_RES.some((re) => re.test(line)))
32
+ .join('\n');
33
+ }
34
+ /**
35
+ * Escreve `.ia-instructions/<ai>.md` (um por IA), `README.md` e `models.json` em `projectDir`,
36
+ * todos derivados de `<kitRoot>/.gemini-instructions.md`. `kitRoot` é a raiz do framework.
37
+ * Nunca lança por IA desconhecida — pula e reporta em `skipped`.
38
+ */
39
+ export function writeAiInstructions(projectDir, aiList, { kitRoot }) {
40
+ const instructionsDir = path.join(projectDir, '.ia-instructions');
41
+ fs.mkdirSync(instructionsDir, { recursive: true });
42
+ const canonicalPath = path.join(kitRoot, CANONICAL_INSTRUCTIONS);
43
+ const canonical = fs.existsSync(canonicalPath) ? fs.readFileSync(canonicalPath, 'utf8') : null;
44
+ const written = [];
45
+ const skipped = [];
46
+ for (const ai of aiList) {
47
+ const label = AI_LABELS[ai];
48
+ if (!label || !canonical) {
49
+ skipped.push(ai);
50
+ continue;
51
+ }
52
+ const others = Object.entries(AI_LABELS)
53
+ .filter(([key]) => key !== ai)
54
+ .map(([, name]) => name);
55
+ const content = canonical
56
+ .replace(/^# Instruções para .+ — Forja$/m, `# Instruções para ${label} — Forja`)
57
+ .replace(/^> Guia para .+ multi-IA por design\.$/m, `> Guia para ${label} operar a Forja. O conteúdo é o mesmo para ${others.slice(0, -1).join(', ')} e ${others.at(-1)} — a Forja é multi-IA por design.`);
58
+ fs.writeFileSync(path.join(instructionsDir, `${ai}.md`), content, 'utf8');
59
+ written.push(ai);
60
+ }
61
+ const indexContent = `# IA Assistants Configuration
62
+
63
+ Este diretório contém instruções específicas para cada IA assistant.
64
+
65
+ ## Gestão de Cotas & Alternância
66
+ Para trocar de IA (ex: se acabar a cota), use o arquivo [models.json](./models.json) para identificar o próximo motor na fila de fallback.
67
+
68
+ ## IAs Configuradas
69
+
70
+ ${aiList.map((ai) => `- [${ai.toUpperCase()}](./${ai}.md)`).join('\n')}
71
+ `;
72
+ fs.writeFileSync(path.join(instructionsDir, 'README.md'), indexContent);
73
+ const modelsJson = {
74
+ active_engine: aiList[0] || 'copilot',
75
+ fallback_chain: [...aiList],
76
+ engines: aiList.reduce((acc, ai) => {
77
+ acc[ai] = { name: ai.toUpperCase(), instruction_file: `.ia-instructions/${ai}.md`, status: 'ready' };
78
+ return acc;
79
+ }, {}),
80
+ };
81
+ fs.writeFileSync(path.join(instructionsDir, 'models.json'), JSON.stringify(modelsJson, null, 2));
82
+ return { written, skipped };
83
+ }
@@ -54,6 +54,11 @@ export interface RunState {
54
54
  }
55
55
  export declare function statePath(root: string, slug: string): string;
56
56
  export declare function loadState(root: string, slug: string, env?: OrchestrateEnv): RunState | null;
57
+ /**
58
+ * Slugs das corridas com estado em `<root>/.context/` (SPEC-044). Restrito a esse diretório — não
59
+ * varre projetos gerados. Nunca lança: `[]` quando não há `.context/` ou nenhuma corrida.
60
+ */
61
+ export declare function listRuns(root: string, env?: OrchestrateEnv): string[];
57
62
  /** Abre uma corrida: a cadeia inteira `pending`, a primeira etapa `open`. Recusa sobrescrever. */
58
63
  export declare function startRun({ root, slug, goal }: {
59
64
  root: string;
@@ -38,6 +38,24 @@ export function loadState(root, slug, env = defaultEnv) {
38
38
  return null;
39
39
  }
40
40
  }
41
+ /**
42
+ * Slugs das corridas com estado em `<root>/.context/` (SPEC-044). Restrito a esse diretório — não
43
+ * varre projetos gerados. Nunca lança: `[]` quando não há `.context/` ou nenhuma corrida.
44
+ */
45
+ export function listRuns(root, env = defaultEnv) {
46
+ const dir = path.join(root, '.context');
47
+ let names;
48
+ try {
49
+ names = env.fs.readdirSync(dir);
50
+ }
51
+ catch {
52
+ return [];
53
+ }
54
+ return names
55
+ .map((n) => /^orchestrate-(.+)\.json$/.exec(n)?.[1])
56
+ .filter((s) => typeof s === 'string')
57
+ .sort();
58
+ }
41
59
  function saveState(root, state, env) {
42
60
  const file = statePath(root, state.slug);
43
61
  env.fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -0,0 +1,20 @@
1
+ /**
2
+ * lib/specs-index.ts — leitura do índice de specs SDD (SPEC-044).
3
+ *
4
+ * Extraído de `scripts/hook-session-start.ts` para ser compartilhado entre o hook e
5
+ * `forja status`/`forja next`. Sem dependência de SQLite: é só `specs/<slug>/{spec,plan,tasks}.md`.
6
+ */
7
+ export interface SpecEntry {
8
+ readonly slug: string;
9
+ /** Status declarado em `spec.md`. */
10
+ readonly status: string;
11
+ /** Status de `plan.md`, ou `null` se o arquivo não existe. */
12
+ readonly plan: string | null;
13
+ /** Status de `tasks.md`, ou `null` se o arquivo não existe. */
14
+ readonly tasks: string | null;
15
+ }
16
+ /**
17
+ * Lista as specs versionadas do repo com o status de cada artefato SDD. `root` é a raiz do repo
18
+ * (onde vive `specs/`). Nunca lança.
19
+ */
20
+ export declare function listSpecs(root: string): SpecEntry[];
@@ -0,0 +1,51 @@
1
+ /**
2
+ * lib/specs-index.ts — leitura do índice de specs SDD (SPEC-044).
3
+ *
4
+ * Extraído de `scripts/hook-session-start.ts` para ser compartilhado entre o hook e
5
+ * `forja status`/`forja next`. Sem dependência de SQLite: é só `specs/<slug>/{spec,plan,tasks}.md`.
6
+ */
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+ const STATUS_RE = /-\s*\*\*Status\*\*:\s*([a-z]+)/i;
10
+ function safeReadDir(p) {
11
+ try {
12
+ return fs.readdirSync(p);
13
+ }
14
+ catch {
15
+ return [];
16
+ }
17
+ }
18
+ function statusOf(file) {
19
+ try {
20
+ if (!fs.existsSync(file))
21
+ return null;
22
+ const m = fs.readFileSync(file, 'utf8').match(STATUS_RE);
23
+ return m ? m[1].toLowerCase() : 'unknown';
24
+ }
25
+ catch {
26
+ return null;
27
+ }
28
+ }
29
+ /**
30
+ * Lista as specs versionadas do repo com o status de cada artefato SDD. `root` é a raiz do repo
31
+ * (onde vive `specs/`). Nunca lança.
32
+ */
33
+ export function listSpecs(root) {
34
+ const specsDir = path.join(root, 'specs');
35
+ const out = [];
36
+ for (const slug of safeReadDir(specsDir)) {
37
+ if (slug.startsWith('_') || slug.startsWith('.'))
38
+ continue;
39
+ const dir = path.join(specsDir, slug);
40
+ const specStatus = statusOf(path.join(dir, 'spec.md'));
41
+ if (specStatus === null)
42
+ continue;
43
+ out.push({
44
+ slug,
45
+ status: specStatus,
46
+ plan: statusOf(path.join(dir, 'plan.md')),
47
+ tasks: statusOf(path.join(dir, 'tasks.md')),
48
+ });
49
+ }
50
+ return out;
51
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * lib/sprint-index.ts — leitura da sprint ativa (SPEC-044).
3
+ *
4
+ * `scripts/sprint-manager.ts` só imprime o arquivo; aqui devolvemos dado. Fonte é a mesma:
5
+ * `memory/40-delivery/current-sprint.md` no root dado.
6
+ */
7
+ export interface SprintInfo {
8
+ readonly active: boolean;
9
+ readonly title: string | null;
10
+ /** Itens de checklist (`- [ ]` / `- [x]`) encontrados. */
11
+ readonly items: number;
12
+ readonly done: number;
13
+ }
14
+ /** `null` quando não há sprint ativa. Nunca lança. */
15
+ export declare function readSprint(root: string): SprintInfo | null;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * lib/sprint-index.ts — leitura da sprint ativa (SPEC-044).
3
+ *
4
+ * `scripts/sprint-manager.ts` só imprime o arquivo; aqui devolvemos dado. Fonte é a mesma:
5
+ * `memory/40-delivery/current-sprint.md` no root dado.
6
+ */
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+ /** `null` quando não há sprint ativa. Nunca lança. */
10
+ export function readSprint(root) {
11
+ const sprintFile = path.join(root, 'memory', '40-delivery', 'current-sprint.md');
12
+ let content;
13
+ try {
14
+ if (!fs.existsSync(sprintFile))
15
+ return null;
16
+ content = fs.readFileSync(sprintFile, 'utf8');
17
+ }
18
+ catch {
19
+ return null;
20
+ }
21
+ const lines = content.split('\n');
22
+ const heading = lines.find((l) => /^#{1,3}\s+\S/.test(l));
23
+ const title = heading ? heading.replace(/^#{1,3}\s+/, '').trim() : null;
24
+ let items = 0;
25
+ let done = 0;
26
+ for (const l of lines) {
27
+ if (/^[-*]\s+\[[ xX]\]\s+/.test(l)) {
28
+ items += 1;
29
+ if (/^[-*]\s+\[[xX]\]\s+/.test(l))
30
+ done += 1;
31
+ }
32
+ }
33
+ return { active: true, title, items, done };
34
+ }
@@ -0,0 +1,64 @@
1
+ /**
2
+ * lib/status-model.ts — o modelo de estado que `forja status` e `forja next` compartilham (SPEC-044).
3
+ *
4
+ * `collectStatus` compõe um retrato a partir de coletores que já existem (workspace, sprint,
5
+ * orchestrate, specs, runs, handoffs). Cada coletor falha para `{ available: false, reason }` —
6
+ * a função **nunca lança**. `recommendNext` é pura sobre esse modelo: a escada de prioridade da
7
+ * AC-4, determinística.
8
+ */
9
+ import { type SpecEntry } from './specs-index.ts';
10
+ import { type SprintInfo } from './sprint-index.ts';
11
+ import { type OpenHandoff } from './handoffs-index.ts';
12
+ export type Sub<T> = {
13
+ readonly available: true;
14
+ readonly value: T;
15
+ } | {
16
+ readonly available: false;
17
+ readonly reason: string;
18
+ };
19
+ export interface OrchestrateRun {
20
+ readonly slug: string;
21
+ readonly goal: string;
22
+ /** id da etapa aberta, ou `null` se a corrida terminou. */
23
+ readonly openStage: string | null;
24
+ /** veredito gravado na etapa aberta (`gate reprovou (exit N)`, `plan.md draft`, …), ou `null`. */
25
+ readonly openVerdict: string | null;
26
+ readonly concluded: boolean;
27
+ }
28
+ export interface RecentRun {
29
+ readonly cmd: string;
30
+ readonly exitCode: number;
31
+ readonly ts: string;
32
+ }
33
+ export interface StatusModel {
34
+ readonly workspace: {
35
+ readonly root: string;
36
+ readonly source: string;
37
+ readonly exists: boolean;
38
+ readonly memoryIndexed: boolean;
39
+ };
40
+ readonly sprint: Sub<SprintInfo | null>;
41
+ readonly orchestrate: Sub<{
42
+ readonly runs: OrchestrateRun[];
43
+ }>;
44
+ readonly specs: Sub<SpecEntry[]>;
45
+ readonly recentRuns: Sub<RecentRun[]>;
46
+ readonly handoffs: Sub<OpenHandoff[]>;
47
+ }
48
+ export interface NextAction {
49
+ readonly action: string;
50
+ readonly command: string;
51
+ readonly reason: string;
52
+ }
53
+ /**
54
+ * `repoRoot` é a raiz onde vivem `specs/`, `memory/` e `.context/orchestrate-*.json` (o repo do
55
+ * framework, ou um projeto gerado). Workspace e memória são resolvidos internamente.
56
+ */
57
+ export declare function collectStatus(repoRoot: string, opts?: {
58
+ runsLimit?: number;
59
+ }): Promise<StatusModel>;
60
+ /**
61
+ * A escada de prioridade da AC-4. Pura, determinística: os ramos são testados na ordem e o
62
+ * primeiro que casa vence — empates são impossíveis por construção.
63
+ */
64
+ export declare function recommendNext(model: StatusModel): NextAction;
@@ -0,0 +1,180 @@
1
+ /**
2
+ * lib/status-model.ts — o modelo de estado que `forja status` e `forja next` compartilham (SPEC-044).
3
+ *
4
+ * `collectStatus` compõe um retrato a partir de coletores que já existem (workspace, sprint,
5
+ * orchestrate, specs, runs, handoffs). Cada coletor falha para `{ available: false, reason }` —
6
+ * a função **nunca lança**. `recommendNext` é pura sobre esse modelo: a escada de prioridade da
7
+ * AC-4, determinística.
8
+ */
9
+ import fs from 'node:fs';
10
+ import path from 'node:path';
11
+ import { getWorkspaceInfo, getWorkspaceContextDir, getWorkspaceDbPath } from "./workspace.js";
12
+ import { listSpecs } from "./specs-index.js";
13
+ import { readSprint } from "./sprint-index.js";
14
+ import { openHandoffs } from "./handoffs-index.js";
15
+ import { listRuns, loadState } from "./orchestrate.js";
16
+ function ok(value) {
17
+ return { available: true, value };
18
+ }
19
+ function unavailable(reason) {
20
+ return { available: false, reason };
21
+ }
22
+ function reasonOf(e) {
23
+ return e instanceof Error ? e.message : String(e);
24
+ }
25
+ function readRecentRuns(contextDir, limit) {
26
+ const file = path.join(contextDir, 'forja-runs.jsonl');
27
+ if (!fs.existsSync(file))
28
+ return [];
29
+ const raw = fs.readFileSync(file, 'utf8').trim();
30
+ if (!raw)
31
+ return [];
32
+ const out = [];
33
+ for (const line of raw.split('\n').slice(-limit)) {
34
+ try {
35
+ const e = JSON.parse(line);
36
+ out.push({ cmd: String(e.cmd ?? '?'), exitCode: Number(e.exitCode ?? -1), ts: String(e.ts ?? '') });
37
+ }
38
+ catch {
39
+ /* linha corrompida: pula */
40
+ }
41
+ }
42
+ return out.reverse(); // mais recente primeiro
43
+ }
44
+ /**
45
+ * `repoRoot` é a raiz onde vivem `specs/`, `memory/` e `.context/orchestrate-*.json` (o repo do
46
+ * framework, ou um projeto gerado). Workspace e memória são resolvidos internamente.
47
+ */
48
+ export async function collectStatus(repoRoot, opts = {}) {
49
+ const runsLimit = opts.runsLimit ?? 5;
50
+ const wi = getWorkspaceInfo();
51
+ let memoryIndexed = false;
52
+ try {
53
+ memoryIndexed = fs.existsSync(getWorkspaceDbPath());
54
+ }
55
+ catch {
56
+ memoryIndexed = false;
57
+ }
58
+ const workspace = { root: wi.root, source: wi.source, exists: wi.exists, memoryIndexed };
59
+ let sprint;
60
+ try {
61
+ sprint = ok(readSprint(repoRoot));
62
+ }
63
+ catch (e) {
64
+ sprint = unavailable(reasonOf(e));
65
+ }
66
+ let orchestrate;
67
+ try {
68
+ const runs = listRuns(repoRoot).map((slug) => {
69
+ const st = loadState(repoRoot, slug);
70
+ if (!st)
71
+ return { slug, goal: '', openStage: null, openVerdict: null, concluded: false };
72
+ const concluded = st.current >= st.stages.length;
73
+ const open = concluded ? null : st.stages[st.current];
74
+ return {
75
+ slug,
76
+ goal: st.goal,
77
+ openStage: open ? open.id : null,
78
+ openVerdict: open?.verdict ?? null,
79
+ concluded,
80
+ };
81
+ });
82
+ orchestrate = ok({ runs });
83
+ }
84
+ catch (e) {
85
+ orchestrate = unavailable(reasonOf(e));
86
+ }
87
+ let specs;
88
+ try {
89
+ specs = ok(listSpecs(repoRoot));
90
+ }
91
+ catch (e) {
92
+ specs = unavailable(reasonOf(e));
93
+ }
94
+ let recentRuns;
95
+ try {
96
+ const dir = wi.exists ? getWorkspaceContextDir() : path.join(repoRoot, '.context');
97
+ recentRuns = ok(readRecentRuns(dir, runsLimit));
98
+ }
99
+ catch (e) {
100
+ recentRuns = unavailable(reasonOf(e));
101
+ }
102
+ let handoffs;
103
+ try {
104
+ handoffs = ok(await openHandoffs());
105
+ }
106
+ catch (e) {
107
+ handoffs = unavailable(reasonOf(e));
108
+ }
109
+ return { workspace, sprint, orchestrate, specs, recentRuns, handoffs };
110
+ }
111
+ /**
112
+ * A escada de prioridade da AC-4. Pura, determinística: os ramos são testados na ordem e o
113
+ * primeiro que casa vence — empates são impossíveis por construção.
114
+ */
115
+ export function recommendNext(model) {
116
+ // 1 — workspace ausente
117
+ if (!model.workspace.exists) {
118
+ return {
119
+ action: 'setup',
120
+ command: 'forja setup',
121
+ reason: `workspace não existe em ${model.workspace.root}`,
122
+ };
123
+ }
124
+ // 2 — memória não indexada
125
+ if (!model.workspace.memoryIndexed) {
126
+ return {
127
+ action: 'sync',
128
+ command: 'forja sync:universal',
129
+ reason: 'a memória universal (SQLite) ainda não foi indexada',
130
+ };
131
+ }
132
+ // 3 e 4 — corrida orchestrate aberta
133
+ if (model.orchestrate.available) {
134
+ const open = model.orchestrate.value.runs.find((r) => !r.concluded && r.openStage);
135
+ if (open) {
136
+ const red = open.openVerdict && open.openVerdict !== 'gate verde';
137
+ return {
138
+ action: 'orchestrate:advance',
139
+ command: `forja orchestrate:advance ${open.slug}`,
140
+ reason: red
141
+ ? `corrida "${open.slug}" travada na etapa ${open.openStage}: ${open.openVerdict} — corrija e reavance`
142
+ : `corrida "${open.slug}" na etapa ${open.openStage} — feito o trabalho, rode o gate`,
143
+ };
144
+ }
145
+ }
146
+ // 5 e 6 — specs pendentes
147
+ if (model.specs.available) {
148
+ const specs = model.specs.value;
149
+ const needPlan = specs.find((s) => s.status === 'approved' && s.plan !== 'approved');
150
+ if (needPlan) {
151
+ return {
152
+ action: 'spec:plan',
153
+ command: `forja spec:plan ${needPlan.slug}`,
154
+ reason: `spec "${needPlan.slug}" aprovada, plan.md ainda não aprovado`,
155
+ };
156
+ }
157
+ const needTasks = specs.find((s) => s.plan === 'approved' && s.tasks !== 'approved' && s.status !== 'done');
158
+ if (needTasks) {
159
+ return {
160
+ action: 'spec:tasks',
161
+ command: `forja spec:tasks ${needTasks.slug}`,
162
+ reason: `plan de "${needTasks.slug}" aprovado, tasks.md ainda não aprovado`,
163
+ };
164
+ }
165
+ const implementing = specs.find((s) => s.status === 'implementing');
166
+ if (implementing) {
167
+ return {
168
+ action: 'spec:check',
169
+ command: `forja spec:check ${implementing.slug}`,
170
+ reason: `spec "${implementing.slug}" em implementação — valide os ACs com spec:check e a bateria`,
171
+ };
172
+ }
173
+ }
174
+ // 7 — nada pendente
175
+ return {
176
+ action: 'orchestrate',
177
+ command: 'forja orchestrate "<objetivo>" --slug <slug>',
178
+ reason: 'nenhuma pendência detectada — abra uma corrida, ou `forja spec:new <slug>` para uma feature nova',
179
+ };
180
+ }
@@ -16,6 +16,8 @@ export declare class EvaluationEngine {
16
16
  constructor(source: EvaluationObservationSource);
17
17
  evaluate(input: EvaluationRequest): Promise<EvaluationReport>;
18
18
  private matches;
19
+ /** Percentil por interpolação linear (`p·(n-1)`); `[]` → 0. SPEC-049. */
20
+ private percentile;
19
21
  private metrics;
20
22
  private repeatedInputCount;
21
23
  private rate;