@codexa/cli 9.0.8 → 9.0.9

package/context/domains.test.ts

@@ -11,6 +11,7 @@ import type { ContextSection } from "./assembly";
 function makeSections(): ContextSection[] {
   return [
     { name: "STANDARDS", content: "...", priority: 1 },
+    { name: "REFERENCIAS", content: "...", priority: 2 },
     { name: "ALERTAS", content: "...", priority: 2 },
     { name: "ARQUITETURA", content: "...", priority: 3 },
     { name: "DECISOES", content: "...", priority: 4 },
@@ -119,7 +120,7 @@ describe("adjustSectionPriorities", () => {
   it("null domain passes all sections through unchanged", () => {
     const sections = makeSections();
     const result = adjustSectionPriorities(sections, null);
-    expect(result).toHaveLength(12);
+    expect(result).toHaveLength(13);
     expect(result).toEqual(sections);
   });
 
@@ -127,8 +128,9 @@ describe("adjustSectionPriorities", () => {
     const result = adjustSectionPriorities(makeSections(), "explore");
     const names = result.map(s => s.name);
 
-    // explore profile: 7 sections have relevance 0
+    // explore profile: 8 sections have relevance 0
     expect(names).not.toContain("STANDARDS");
+    expect(names).not.toContain("REFERENCIAS");
     expect(names).not.toContain("CONTEXTO DE TASKS ANTERIORES");
     expect(names).not.toContain("GRAPH");
     expect(names).not.toContain("PRODUTO");
@@ -189,7 +191,7 @@ describe("adjustSectionPriorities", () => {
     const result = adjustSectionPriorities(makeSections(), "testing");
     const names = result.map(s => s.name);
     expect(names).not.toContain("PRODUTO");
-    expect(result).toHaveLength(11);
+    expect(result).toHaveLength(12);
   });
 
   it("testing domain boosts CONTEXTO DE TASKS ANTERIORES (relevance=3)", () => {
@@ -212,10 +214,30 @@ describe("adjustSectionPriorities", () => {
     expect(produto?.priority).toBe(5);
   });
 
-  it("security domain excludes PRODUTO (relevance=0)", () => {
+  it("backend domain boosts REFERENCIAS (relevance=3)", () => {
+    const result = adjustSectionPriorities(makeSections(), "backend");
+    const refs = result.find(s => s.name === "REFERENCIAS");
+    // backend: REFERENCIAS=3 (base 2 + offset -2 = 0 → floor 1)
+    expect(refs?.priority).toBe(1);
+  });
+
+  it("explore domain excludes REFERENCIAS (relevance=0)", () => {
+    const result = adjustSectionPriorities(makeSections(), "explore");
+    const names = result.map(s => s.name);
+    expect(names).not.toContain("REFERENCIAS");
+  });
+
+  it("architecture domain excludes REFERENCIAS (relevance=0)", () => {
+    const result = adjustSectionPriorities(makeSections(), "architecture");
+    const names = result.map(s => s.name);
+    expect(names).not.toContain("REFERENCIAS");
+  });
+
+  it("security domain excludes PRODUTO and REFERENCIAS (relevance=0)", () => {
     const result = adjustSectionPriorities(makeSections(), "security");
     const names = result.map(s => s.name);
     expect(names).not.toContain("PRODUTO");
+    expect(names).not.toContain("REFERENCIAS");
     expect(result).toHaveLength(11);
   });
 
@@ -235,12 +257,12 @@ describe("adjustSectionPriorities", () => {
 
 describe("DOMAIN_PROFILES completeness", () => {
   const allSectionNames = [
-    "STANDARDS", "ALERTAS", "ARQUITETURA", "DECISOES",
+    "STANDARDS", "REFERENCIAS", "ALERTAS", "ARQUITETURA", "DECISOES",
     "CONTEXTO DE TASKS ANTERIORES", "GRAPH", "PRODUTO",
     "DISCOVERIES", "UTILITIES", "PATTERNS", "HINTS", "STACK",
   ];
 
-  it("every domain profile covers all 12 sections", () => {
+  it("every domain profile covers all 13 sections", () => {
     for (const [domain, profile] of Object.entries(DOMAIN_PROFILES)) {
       for (const section of allSectionNames) {
         expect(profile[section as keyof typeof profile]).toBeDefined();

package/context/domains.ts

@@ -19,6 +19,7 @@ export type Relevance = 0 | 1 | 2 | 3;
 
 export type SectionName =
   | "STANDARDS"
+  | "REFERENCIAS"
   | "ALERTAS"
   | "ARQUITETURA"
   | "DECISOES"
@@ -58,42 +59,42 @@ export const AGENT_DOMAIN: Record<string, AgentDomain> = {
 
 export const DOMAIN_PROFILES: Record<AgentDomain, DomainProfile> = {
   backend: {
-    "STANDARDS": 3, "ALERTAS": 3, "ARQUITETURA": 2, "DECISOES": 3,
+    "STANDARDS": 3, "REFERENCIAS": 3, "ALERTAS": 3, "ARQUITETURA": 2, "DECISOES": 3,
     "CONTEXTO DE TASKS ANTERIORES": 2, "GRAPH": 2, "PRODUTO": 1,
     "DISCOVERIES": 2, "UTILITIES": 3, "PATTERNS": 2, "HINTS": 2, "STACK": 2,
   },
   frontend: {
-    "STANDARDS": 3, "ALERTAS": 3, "ARQUITETURA": 2, "DECISOES": 3,
+    "STANDARDS": 3, "REFERENCIAS": 3, "ALERTAS": 3, "ARQUITETURA": 2, "DECISOES": 3,
     "CONTEXTO DE TASKS ANTERIORES": 2, "GRAPH": 2, "PRODUTO": 3,
     "DISCOVERIES": 2, "UTILITIES": 3, "PATTERNS": 3, "HINTS": 2, "STACK": 2,
   },
   database: {
-    "STANDARDS": 3, "ALERTAS": 3, "ARQUITETURA": 3, "DECISOES": 3,
+    "STANDARDS": 3, "REFERENCIAS": 3, "ALERTAS": 3, "ARQUITETURA": 3, "DECISOES": 3,
     "CONTEXTO DE TASKS ANTERIORES": 2, "GRAPH": 2, "PRODUTO": 0,
     "DISCOVERIES": 2, "UTILITIES": 1, "PATTERNS": 2, "HINTS": 2, "STACK": 3,
   },
   testing: {
-    "STANDARDS": 3, "ALERTAS": 3, "ARQUITETURA": 1, "DECISOES": 2,
+    "STANDARDS": 3, "REFERENCIAS": 3, "ALERTAS": 3, "ARQUITETURA": 1, "DECISOES": 2,
     "CONTEXTO DE TASKS ANTERIORES": 3, "GRAPH": 1, "PRODUTO": 0,
     "DISCOVERIES": 2, "UTILITIES": 3, "PATTERNS": 3, "HINTS": 2, "STACK": 1,
   },
   review: {
-    "STANDARDS": 3, "ALERTAS": 3, "ARQUITETURA": 3, "DECISOES": 3,
+    "STANDARDS": 3, "REFERENCIAS": 1, "ALERTAS": 3, "ARQUITETURA": 3, "DECISOES": 3,
     "CONTEXTO DE TASKS ANTERIORES": 2, "GRAPH": 2, "PRODUTO": 1,
     "DISCOVERIES": 2, "UTILITIES": 3, "PATTERNS": 2, "HINTS": 3, "STACK": 2,
   },
   security: {
-    "STANDARDS": 3, "ALERTAS": 3, "ARQUITETURA": 2, "DECISOES": 2,
+    "STANDARDS": 3, "REFERENCIAS": 0, "ALERTAS": 3, "ARQUITETURA": 2, "DECISOES": 2,
     "CONTEXTO DE TASKS ANTERIORES": 1, "GRAPH": 1, "PRODUTO": 0,
     "DISCOVERIES": 2, "UTILITIES": 1, "PATTERNS": 1, "HINTS": 2, "STACK": 3,
   },
   explore: {
-    "STANDARDS": 0, "ALERTAS": 1, "ARQUITETURA": 3, "DECISOES": 1,
+    "STANDARDS": 0, "REFERENCIAS": 0, "ALERTAS": 1, "ARQUITETURA": 3, "DECISOES": 1,
     "CONTEXTO DE TASKS ANTERIORES": 0, "GRAPH": 0, "PRODUTO": 0,
     "DISCOVERIES": 1, "UTILITIES": 0, "PATTERNS": 0, "HINTS": 0, "STACK": 3,
   },
   architecture: {
-    "STANDARDS": 2, "ALERTAS": 2, "ARQUITETURA": 3, "DECISOES": 3,
+    "STANDARDS": 2, "REFERENCIAS": 0, "ALERTAS": 2, "ARQUITETURA": 3, "DECISOES": 3,
     "CONTEXTO DE TASKS ANTERIORES": 2, "GRAPH": 2, "PRODUTO": 3,
     "DISCOVERIES": 2, "UTILITIES": 1, "PATTERNS": 2, "HINTS": 1, "STACK": 3,
   },

package/context/generator.ts

@@ -18,6 +18,7 @@ import {
     buildGraphSection,
     buildStackSection,
     buildHintsSection,
+    buildReferencesSection,
 } from "./sections";
 
 // v9.0: Contexto minimo para subagent (max ~2KB)
@@ -253,6 +254,7 @@ export function getContextForSubagent(taskId: number): string {
         buildProductSection(data),
         buildArchitectureSection(data),
         buildStandardsSection(data),
+        buildReferencesSection(data),
         buildDecisionsSection(data),
         buildReasoningSection(data),
         buildAlertsSection(data),

package/context/index.ts

@@ -18,4 +18,7 @@ export {
     buildGraphSection,
     buildStackSection,
     buildHintsSection,
+    buildReferencesSection,
 } from "./sections";
+export { findReferenceFiles } from "./references";
+export type { ReferenceFile } from "./references";

package/context/references.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { join } from "path";
+import { mkdirSync, rmSync, writeFileSync } from "fs";
+import { findReferenceFiles } from "./references";
+
+// ── Test fixtures ────────────────────────────────────────────
+
+const TMP_DIR = join(import.meta.dir, "__test_refs__");
+
+function ensureDir(dir: string) {
+  mkdirSync(dir, { recursive: true });
+}
+
+function writeTmpFile(relativePath: string, content: string): string {
+  const full = join(TMP_DIR, relativePath);
+  ensureDir(join(full, ".."));
+  writeFileSync(full, content);
+  return relativePath;
+}
+
+beforeAll(() => {
+  ensureDir(TMP_DIR);
+
+  // src/routes/ — 3 route files of different sizes
+  writeTmpFile("src/routes/users.ts", "export function getUsers() { return []; }\nexport function createUser() { return {}; }\n// more code here to make it larger\n".repeat(5));
+  writeTmpFile("src/routes/products.ts", "export function getProducts() { return []; }\n");
+  writeTmpFile("src/routes/orders.ts", "export function getOrders() { return []; }\nexport function createOrder() { return {}; }\n");
+
+  // src/services/ — 2 service files
+  writeTmpFile("src/services/auth.service.ts", "export class AuthService { login() {} logout() {} verify() {} }\n".repeat(3));
+  writeTmpFile("src/services/user.service.ts", "export class UserService { getById() {} }\n");
+
+  // src/components/ — React components
+  writeTmpFile("src/components/Button.tsx", "export function Button() { return <button/>; }\n");
+  writeTmpFile("src/components/Card.tsx", "export function Card() { return <div/>; }\nexport function CardHeader() { return <div/>; }\n".repeat(3));
+
+  // src/modules/users/ and src/modules/payments/ — parallel structure
+  writeTmpFile("src/modules/users/route.ts", "export function usersRoute() { return {}; }\n".repeat(4));
+  writeTmpFile("src/modules/users/service.ts", "export function usersService() {}\n");
+  writeTmpFile("src/modules/payments/service.ts", "export function paymentsService() {}\n");
+
+  // tests/ — test files
+  writeTmpFile("tests/routes/users.test.ts", "describe('users', () => { it('works', () => {}); });\n".repeat(2));
+
+  // node_modules/ — should be ignored
+  writeTmpFile("node_modules/pkg/index.ts", "export const x = 1;\n");
+
+  // Non-code file
+  writeTmpFile("docs/readme.md", "# Readme\n");
+});
+
+afterAll(() => {
+  rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+// ── Tests ────────────────────────────────────────────────────
+
+describe("findReferenceFiles", () => {
+  it("finds siblings in the same directory", () => {
+    // Target: new file in src/routes/ — should find existing routes
+    const refs = findReferenceFiles(["src/routes/payments.ts"], TMP_DIR);
+
+    expect(refs.length).toBeGreaterThanOrEqual(1);
+    expect(refs[0].reason).toBe("mesmo diretorio");
+    // Should pick the largest sibling (users.ts has the most content)
+    expect(refs[0].path).toBe("src/routes/users.ts");
+  });
+
+  it("prioritizes largest file as reference", () => {
+    const refs = findReferenceFiles(["src/components/Modal.tsx"], TMP_DIR);
+
+    expect(refs.length).toBe(1);
+    // Card.tsx is larger than Button.tsx
+    expect(refs[0].path).toBe("src/components/Card.tsx");
+  });
+
+  it("finds namesakes when no siblings exist", () => {
+    // Target: src/modules/payments/route.ts — no siblings, but src/modules/users/route.ts exists
+    const refs = findReferenceFiles(["src/modules/payments/route.ts"], TMP_DIR);
+
+    expect(refs.length).toBeGreaterThanOrEqual(1);
+    const paths = refs.map(r => r.path);
+    // Should find the namesake route.ts or a sibling service.ts
+    expect(
+      paths.some(p => p.includes("route.ts") || p.includes("service.ts"))
+    ).toBe(true);
+  });
+
+  it("returns empty for non-code files", () => {
+    const refs = findReferenceFiles(["docs/notes.md"], TMP_DIR);
+    expect(refs).toEqual([]);
+  });
+
+  it("returns empty for empty task files", () => {
+    expect(findReferenceFiles([], TMP_DIR)).toEqual([]);
+  });
+
+  it("returns empty for null/undefined", () => {
+    expect(findReferenceFiles(null as any, TMP_DIR)).toEqual([]);
+    expect(findReferenceFiles(undefined as any, TMP_DIR)).toEqual([]);
+  });
+
+  it("ignores node_modules", () => {
+    const refs = findReferenceFiles(["node_modules/pkg/new.ts"], TMP_DIR);
+    // Even if node_modules has .ts files, targets in ignored dirs get no refs
+    // (the target itself is filtered by extension check, not by ignored dir)
+    // But results should never point INTO node_modules
+    for (const ref of refs) {
+      expect(ref.path).not.toContain("node_modules");
+    }
+  });
+
+  it("limits to 3 references max", () => {
+    const refs = findReferenceFiles([
+      "src/routes/payments.ts",
+      "src/services/payment.service.ts",
+      "src/components/Modal.tsx",
+      "tests/routes/products.test.ts",
+    ], TMP_DIR);
+
+    expect(refs.length).toBeLessThanOrEqual(3);
+  });
+
+  it("deduplicates references", () => {
+    const refs = findReferenceFiles([
+      "src/routes/payments.ts",
+      "src/routes/invoices.ts",
+    ], TMP_DIR);
+
+    const paths = refs.map(r => r.path);
+    const unique = new Set(paths);
+    expect(paths.length).toBe(unique.size);
+  });
+
+  it("handles Windows-style backslash paths", () => {
+    const refs = findReferenceFiles(["src\\routes\\payments.ts"], TMP_DIR);
+    expect(refs.length).toBeGreaterThanOrEqual(1);
+    // All returned paths should use forward slashes
+    for (const ref of refs) {
+      expect(ref.path).not.toContain("\\");
+    }
+  });
+
+  it("finds reference for test files", () => {
+    const refs = findReferenceFiles(["tests/routes/products.test.ts"], TMP_DIR);
+    expect(refs.length).toBeGreaterThanOrEqual(1);
+    expect(refs[0].path).toContain("users.test.ts");
+  });
+
+  it("uses parent directory as fallback", () => {
+    // Target in a new subdirectory with no siblings or namesakes
+    writeTmpFile("src/features/billing/handler.ts", "export function handle() {}\n");
+    const refs = findReferenceFiles(["src/features/billing/processor.ts"], TMP_DIR);
+    // Should find handler.ts as sibling
+    if (refs.length > 0) {
+      expect(refs[0].path).toContain("billing");
+    }
+  });
+});

package/context/references.ts

@@ -0,0 +1,159 @@
+import { join, dirname, basename, extname, resolve, relative } from "path";
+import { globSync } from "fs";
+
+// ═══════════════════════════════════════════════════════════════
+// REFERENCE FILES — Pattern by Example (v9.5)
+//
+// Finds existing files similar to task targets so subagents can
+// read them and replicate the coding style exactly.
+// ═══════════════════════════════════════════════════════════════
+
+export interface ReferenceFile {
+  path: string;
+  reason: string;
+}
+
+const IGNORED_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", ".codexa",
+  ".nuxt", ".output", "coverage", "__pycache__", ".venv", "vendor",
+  "target", "bin", "obj",
+]);
+
+const CODE_EXTENSIONS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte",
+  ".go", ".rs", ".py", ".cs", ".kt", ".java",
+  ".dart", ".php", ".rb", ".swift",
+]);
+
+function normalizePath(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+function isIgnored(filePath: string): boolean {
+  const parts = normalizePath(filePath).split("/");
+  return parts.some(part => IGNORED_DIRS.has(part));
+}
+
+function getFileSize(filePath: string): number {
+  try {
+    return Bun.file(filePath).size;
+  } catch {
+    return 0;
+  }
+}
+
+function fileExists(filePath: string): boolean {
+  try {
+    return Bun.file(filePath).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+function globFiles(pattern: string, cwd: string): string[] {
+  try {
+    const glob = new Bun.Glob(pattern);
+    const results: string[] = [];
+    for (const match of glob.scanSync({ cwd, dot: false })) {
+      const full = join(cwd, match);
+      if (!isIgnored(full)) {
+        results.push(normalizePath(full));
+      }
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+
+function pickLargest(files: string[]): string | null {
+  if (files.length === 0) return null;
+
+  let best = files[0];
+  let bestSize = getFileSize(files[0]);
+
+  for (let i = 1; i < files.length; i++) {
+    const size = getFileSize(files[i]);
+    if (size > bestSize) {
+      best = files[i];
+      bestSize = size;
+    }
+  }
+
+  return bestSize > 0 ? best : null;
+}
+
+/**
+ * Find reference files for a set of task target files.
+ *
+ * Strategy per target file:
+ * 1. Siblings — other files in the same directory with same extension
+ * 2. Namesakes — files with same basename in other directories
+ * 3. Parent — files with same extension in parent directory tree
+ *
+ * Returns max 3 deduplicated reference file paths.
+ */
+export function findReferenceFiles(
+  taskFiles: string[],
+  projectRoot: string,
+): ReferenceFile[] {
+  if (!taskFiles || taskFiles.length === 0) return [];
+
+  const seen = new Set<string>();
+  const results: ReferenceFile[] = [];
+  const normalizedRoot = normalizePath(resolve(projectRoot));
+
+  for (const rawTarget of taskFiles) {
+    if (results.length >= 3) break;
+
+    const target = normalizePath(resolve(projectRoot, rawTarget));
+    const ext = extname(target);
+    const base = basename(target);
+    const dir = dirname(target);
+
+    if (!ext || !CODE_EXTENSIONS.has(ext)) continue;
+
+    // Strategy 1: Siblings (same directory, same extension)
+    const siblings = globFiles(`*${ext}`, dir)
+      .filter(f => f !== target && !seen.has(f) && fileExists(f));
+
+    const bestSibling = pickLargest(siblings);
+    if (bestSibling) {
+      const rel = normalizePath(relative(normalizedRoot, bestSibling));
+      seen.add(bestSibling);
+      results.push({ path: rel, reason: "mesmo diretorio" });
+      continue;
+    }
+
+    // Strategy 2: Namesakes (same filename in other directories)
+    const namesakes = globFiles(`**/${base}`, normalizedRoot)
+      .filter(f => f !== target && !seen.has(f) && fileExists(f));
+
+    if (namesakes.length > 0) {
+      // Pick the one closest by path depth similarity
+      const bestNamesake = pickLargest(namesakes);
+      if (bestNamesake) {
+        const rel = normalizePath(relative(normalizedRoot, bestNamesake));
+        seen.add(bestNamesake);
+        results.push({ path: rel, reason: "mesmo tipo de arquivo" });
+        continue;
+      }
+    }
+
+    // Strategy 3: Parent directory search (same extension, one level up)
+    const parentDir = dirname(dir);
+    if (parentDir !== dir) {
+      const parentFiles = globFiles(`**/*${ext}`, parentDir)
+        .filter(f => f !== target && !seen.has(f) && fileExists(f));
+
+      const bestParent = pickLargest(parentFiles);
+      if (bestParent) {
+        const rel = normalizePath(relative(normalizedRoot, bestParent));
+        seen.add(bestParent);
+        results.push({ path: rel, reason: "arquivo similar proximo" });
+      }
+    }
+  }
+
+  return results;
+}

package/context/sections.ts

@@ -1,6 +1,7 @@
 import { getUtilitiesForContext, getAgentHints } from "../db/schema";
 import type { ContextSection, ContextData } from "./assembly";
 import { getAgentDomain, domainToScope } from "./domains";
+import { findReferenceFiles } from "./references";
 
 // ── Section Builders ──────────────────────────────────────────
 
@@ -245,3 +246,18 @@ ${hints.map(h => `- ${h}`).join("\n")}
 `;
     return { name: "HINTS", content, priority: 10 };
 }
+
+export function buildReferencesSection(data: ContextData): ContextSection | null {
+    if (data.taskFiles.length === 0) return null;
+
+    const projectRoot = process.cwd();
+    const refs = findReferenceFiles(data.taskFiles, projectRoot);
+    if (refs.length === 0) return null;
+
+    const content = `
+### REFERENCIA DE ESTILO (${refs.length})
+**ANTES de criar/modificar arquivos, leia estas referencias e replique o mesmo estilo** (nomenclatura, estrutura, imports, error handling):
+${refs.map(r => `- \`${r.path}\` (${r.reason})`).join("\n")}
+`;
+    return { name: "REFERENCIAS", content, priority: 2 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codexa/cli",
-  "version": "9.0.8",
+  "version": "9.0.9",
   "description": "Orchestrated workflow system for Claude Code - manages feature development through parallel subagents with structured phases, gates, and quality enforcement.",
   "type": "module",
   "bin": {