jarvis-ai-framework 3.2.0 → 5.0.0

package/bin/lib/cli/program.js

@@ -28,7 +28,6 @@ import { tokens } from "../../commands/tokens.js";
 import { map } from "../../commands/map.js";
 import { runCreateMerge } from "../vcs/create-merge.js";
 import { runCreateIssue } from "../vcs/create-issue.js";
-import { runFetchRaw } from "../vcs/fetch-raw.js";
 import { runComment } from "../tasks/comment.js";
 import { fetchFile } from "../docs/fetch-file.js";
 import { formatIDEsList } from "../config/ide-config.js";
@@ -112,33 +111,38 @@ export function buildProgram() {
   const docs = cmd(program, "docs").description("Sincronizar ou publicar documentação");
 
   const docsSyncCmd = cmd(docs, "sync").description(
-    "Sincronizar docs do central-docs (usado por /warm-up)"
+    "Sincronizar docs do Central docs pelo adaptador de CENTRAL_DOCS_STORAGE (usado por /warm-up)"
   );
   withEnvOptions(withLogOptions(docsSyncCmd)).action((options) => docsSync(toLegacyFlags(options)));
 
-  cmd(docs, "fetch")
+  const docsFetchCmd = cmd(docs, "fetch")
     .description(
-      "Buscar um arquivo do central-docs, com cache Redis best-effort (lê CENTRAL_DOCS_REPO do ambiente)"
+      "Buscar um arquivo do Central docs pelo adaptador de CENTRAL_DOCS_STORAGE (com git: pull antes de ler)"
     )
-    .argument("<file-path>", "Path do arquivo dentro do repo central-docs")
-    .argument("[ref]", "Branch/ref", "main")
-    .action(async (filePath, ref) => {
-      try {
-        const content = await fetchFile(filePath, ref);
-        process.stdout.write(content);
-      } catch (error) {
-        console.error(error.message);
-        process.exit(error.code === 404 ? 2 : 1);
-      }
-    });
+    .argument("<file-path>", "Caminho do arquivo dentro do Central docs (ex: CORE/index.md)");
+  withEnvOptions(docsFetchCmd).action(async (filePath, options) => {
+    try {
+      const content = await fetchFile(filePath, { flags: toLegacyFlags(options) });
+      process.stdout.write(content);
+    } catch (error) {
+      console.error(error.message);
+      process.exit(error.code === 404 ? 2 : 1);
+    }
+  });
 
   const docsPublishCmd = cmd(docs, "publish")
-    .description("Publicar documento no central-docs (branch + MR/PR)")
+    .description(
+      "Publicar a consolidação (feature/delivery) no Central docs (pasta: copia e regenera o índice; com git: branch + PR)"
+    )
     .option("--file <path>", "Caminho do arquivo local")
-    .option("--tipo <tipo>", "prd|frd|ard|rfc|swagger|qa-report")
-    .option("--feature <slug>", "Slug da feature (kebab-case)")
+    .option("--tipo <tipo>", "feature|delivery (consolidação do /eng.spec-consolidate)")
+    .option("--produto <produto>", "Pasta do produto no Central docs (padrão: WORKSPACE do ENV.md)")
+    .option("--feature <slug>", "Só se o nome do arquivo fugir do padrão {tipo}-{nome}.md")
     .option("--squad <squad>", "Override do SQUAD do ENV.md")
-    .option("--workspace <workspace>", "Override do WORKSPACE do ENV.md");
+    .option(
+      "--workspace <workspace>",
+      "Override do WORKSPACE do ENV.md (mesmo efeito de --produto)"
+    );
   withEnvOptions(withLogOptions(docsPublishCmd)).action((options) =>
     docsPublish(toLegacyFlags(options))
   );
@@ -201,12 +205,6 @@ export function buildProgram() {
       runCreateIssue({ repo: options.repo, title: options.title, bodyFile: options.bodyFile })
     );
 
-  cmd(vcs, "fetch-raw")
-    .description("Buscar o conteúdo bruto de um arquivo no central-docs (lê CENTRAL_DOCS_REPO)")
-    .argument("[file-path]")
-    .argument("[ref]", "Branch/ref", "main")
-    .action((filePath, ref) => runFetchRaw(filePath, ref));
-
   const tasks = cmd(program, "tasks").description("Adapters de task manager");
 
   cmd(tasks, "comment")

package/bin/lib/docs/fetch-file.js

@@ -1,39 +1,42 @@
 /**
- * @fileoverview Busca um arquivo do central-docs (GitLab/GitHub/Bitbucket), com
- * cache Redis best-effort. Substitui `fetch-file.sh` (removido) — mesmo
- * comportamento, sem subprocess: chama `fetchRawFile` de `vcs/api.js` direto.
+ * @fileoverview Leitura do Central docs pelo adaptador configurado
+ * (`CENTRAL_DOCS_STORAGE`), venha o conteúdo de onde vier.
  * @module docs/fetch-file
  */
 
-import { fetchRawFile } from "../vcs/api.js";
-import { redisGet, redisSetex } from "./redis-cache.js";
+import { loadEnv, resolveEnvPath } from "../env-loader.js";
+import { getStorage } from "./storage/index.js";
 
 /**
- * @param {string} filePath - Path do arquivo dentro do repo central-docs
- * @param {string} [ref] - Branch/ref (padrão: "main")
+ * Carrega o ENV.md e devolve o adaptador do Central docs.
+ * @param {Object} [flags] - `envFile`/`ide` (mesmas opções dos outros comandos)
  * @param {Object} [opts]
- * @param {string} [opts.repo] - CENTRAL_DOCS_REPO (padrão: `process.env.CENTRAL_DOCS_REPO`)
- * @param {string|number} [opts.cacheTtl] - TTL do cache em segundos (padrão: `process.env.CENTRAL_DOCS_CACHE_TTL` ou 3600)
- * @returns {Promise<string>} conteúdo do arquivo
- * @throws {Error} sem `filePath`, sem `repo`, ou erro do adapter (404/401/403 — ver `fetchRawFile`)
+ * @param {string} [opts.cwd]
+ * @param {Object} [opts.deps] - Dependências injetáveis do adaptador (testes)
+ * @returns {{ env: Record<string, string>, root: string, storage: Object|null }}
  */
-export async function fetchFile(filePath, ref = "main", opts = {}) {
+export function openStorageFromEnv(flags = {}, { cwd = process.cwd(), deps } = {}) {
+  const { path, root } = resolveEnvPath(cwd, flags);
+  const env = loadEnv(cwd, path);
+  return { env, root, storage: getStorage(env, { root, deps }) };
+}
+
+/**
+ * Lê um arquivo do Central docs.
+ * @param {string} filePath - Caminho dentro do Central docs (ex: `CORE/index.md`)
+ * @param {Object} [opts]
+ * @param {Object} [opts.storage] - Adaptador já aberto; sem ele, abre pelo ENV.md
+ * @param {Object} [opts.flags]
+ * @returns {Promise<string>}
+ * @throws {Error} sem `filePath`, Central docs desligado, ou `code = 404`
+ */
+export async function fetchFile(filePath, opts = {}) {
   if (!filePath) {
     throw new Error("fetchFile: file-path é obrigatório");
   }
-
-  const repo = opts.repo ?? process.env.CENTRAL_DOCS_REPO;
-  if (!repo) {
-    throw new Error("CENTRAL_DOCS_REPO não definido no ENV.md");
+  const storage = opts.storage ?? openStorageFromEnv(opts.flags).storage;
+  if (!storage) {
+    throw new Error("Central docs desligado (CENTRAL_DOCS_STORAGE vazio no ENV.md).");
   }
-
-  const cacheKey = `docs:${filePath}:${ref}`;
-  const cached = redisGet(cacheKey);
-  if (cached) return cached;
-
-  const content = await fetchRawFile(repo, filePath, ref);
-
-  redisSetex(cacheKey, opts.cacheTtl ?? process.env.CENTRAL_DOCS_CACHE_TTL ?? "3600", content);
-
-  return content;
+  return storage.fetch(filePath);
 }

package/bin/lib/docs/publish-file.js

@@ -1,194 +1,133 @@
 /**
- * @fileoverview Publica um documento no central-docs (branch + commit + MR/PR).
- * Substitui `publish-file.sh` (removido) — chama os adapters de `vcs/api.js`
- * direto, sem subprocess, sem arquivo temporário para passar JSON/body.
+ * @fileoverview Publica no Central docs, pelo adaptador configurado
+ * (`CENTRAL_DOCS_STORAGE`), a consolidação do que foi implementado, gerada pelo
+ * `/eng.spec-consolidate`: o documento da funcionalidade (`feature-*.md`, em
+ * `{SQUAD}/product/{produto}/`) e o registro da entrega (`delivery-*.md`, em
+ * `{SQUAD}/engineering/{produto}/`). Documentos de trabalho (PRD, FRD, ARD, RFC…)
+ * não são publicados. O índice do squad é regenerado a cada publicação.
  * @module docs/publish-file
  */
 
-import { readFileSync } from "node:fs";
-import { validateFrontmatter, extractMetadata } from "./validate-frontmatter.js";
-import { commitFiles, createMergeRequest } from "../vcs/api.js";
-import { fetchFile } from "./fetch-file.js";
-import { redisDel } from "./redis-cache.js";
+import { basename, extname } from "node:path";
+import { validateFrontmatter } from "./validate-frontmatter.js";
 import { logger } from "../utils/logger.js";
 
-const VALID_TYPES = ["prd", "frd", "ard", "rfc", "swagger", "qa-report"];
-
-/**
- * @param {{ tipo: string, squad: string, workspace: string, feature: string, localFile: string }} p
- * @returns {{ destPath: string, area: "product"|"engineering" }}
- */
-export function resolveDestPath({ tipo, squad, workspace, feature, localFile }) {
-  const base = `${squad}/${workspace}`;
-
-  if (tipo === "prd" || tipo === "frd") {
-    return { destPath: `${base}/product/${tipo}-${feature}.md`, area: "product" };
-  }
-  if (tipo === "ard") {
-    return { destPath: `${base}/engineering/ARD/${tipo}-${feature}.md`, area: "engineering" };
-  }
-  if (tipo === "rfc") {
-    return { destPath: `${base}/engineering/RFC/${tipo}-${feature}.md`, area: "engineering" };
-  }
-  if (tipo === "swagger") {
-    const ext = localFile.split(".").pop().toLowerCase();
-    const swaggerExt = ext === "yaml" || ext === "yml" ? ext : ext === "json" ? "json" : null;
-    const destPath = swaggerExt
-      ? `${base}/engineering/swagger/api-${feature}.${swaggerExt}`
-      : `${base}/engineering/swagger/swagger-${feature}.md`; // default: .md (wrapper com metadados)
-    return { destPath, area: "engineering" };
-  }
-  if (tipo === "qa-report") {
-    return { destPath: `${base}/engineering/qa/qa-report-${feature}.md`, area: "engineering" };
+/** @constant {Readonly<Record<string, "product"|"engineering">>} Área de cada tipo */
+export const AREA_BY_TYPE = Object.freeze({
+  feature: "product",
+  delivery: "engineering",
+});
+
+/** @constant {ReadonlyArray<string>} Documentos de trabalho, que não vão mais para o Central docs */
+export const WORKING_DOC_TYPES = Object.freeze([
+  "prd",
+  "frd",
+  "feat",
+  "epic",
+  "story",
+  "task",
+  "ard",
+  "rfc",
+  "swagger",
+  "qa-report",
+]);
+
+/** @constant {ReadonlyArray<string>} Tipos aceitos pelo `jarvis docs publish` */
+export const VALID_TYPES = Object.freeze(Object.keys(AREA_BY_TYPE));
+
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+function assertSegment(label, value) {
+  if (!value || !SEGMENT.test(value)) {
+    throw new Error(
+      `${label} inválido: "${value ?? ""}" (use letras, números, "-" ou "_", sem "/" nem "..")`
+    );
   }
-
-  throw new Error(`Tipo inválido: ${tipo}\nTipos válidos: ${VALID_TYPES.join(", ")}`);
 }
 
 /**
- * Insere `newLine` logo após o header `## {area}` — sem nunca descartar uma
- * linha existente. O `publish-file.sh` original usava `getline` do AWK para
- * "pular" a linha seguinte ao header antes de imprimir a nova entrada; essa
- * linha pulada nunca era reimpressa, o que apagava silenciosamente a entrada
- * anterior do índice na segunda publicação numa mesma seção (reproduzido e
- * documentado em `architecture.md` desta sessão, seção 3.4).
- * @param {string} content
- * @param {"product"|"engineering"} area
- * @param {string} newLine
- * @returns {{ content: string, found: boolean }}
+ * Calcula o destino do documento no Central docs.
+ * O nome é o do arquivo local quando ele já segue `{tipo}-…` (ex: `feature-checkout.md`,
+ * `delivery-2026-10-15-task-123.md`); senão vem de `--feature` (`{tipo}-{feature}.md`).
+ *
+ * @param {Object} p
+ * @param {string} p.tipo
+ * @param {string} p.squad
+ * @param {string} p.produto - Padrão: WORKSPACE (o caller resolve)
+ * @param {string} p.localFile
+ * @param {string} [p.feature]
+ * @returns {{ destPath: string, area: "product"|"engineering", fileName: string }}
  */
-export function insertIndexLine(content, area, newLine) {
-  const lines = content.split("\n");
-  const headerPattern = /^## (product|engineering)\b/;
-
-  for (let i = 0; i < lines.length; i++) {
-    const match = lines[i].match(headerPattern);
-    if (match && match[1] === area) {
-      lines.splice(i + 1, 0, newLine);
-      return { content: lines.join("\n"), found: true };
-    }
+export function resolveDestPath({ tipo, squad, produto, localFile, feature }) {
+  const area = AREA_BY_TYPE[tipo];
+  if (!area && WORKING_DOC_TYPES.includes(tipo)) {
+    throw new Error(
+      `O Central docs guarda só o que foi implementado: "${tipo}" é um documento de trabalho e fica em docs/jarvis/.\n` +
+        "Gere a consolidação com /eng.spec-consolidate (tipos: feature, delivery)."
+    );
+  }
+  if (!area) {
+    throw new Error(`Tipo inválido: ${tipo}\nTipos válidos: ${VALID_TYPES.join(", ")}`);
+  }
+  assertSegment("Squad", squad);
+  assertSegment("Produto", produto);
+
+  const local = basename(localFile);
+  const ext = extname(local).toLowerCase() || ".md";
+  const followsPattern = local.toLowerCase().startsWith(`${tipo}-`) && ext === ".md";
+
+  let fileName;
+  if (followsPattern) {
+    fileName = local;
+  } else if (feature) {
+    assertSegment("Feature", feature);
+    fileName = `${tipo}-${feature}${ext}`;
+  } else {
+    throw new Error(
+      `O arquivo "${local}" não segue o padrão ${tipo}-{nome}.md.\n` +
+        `Renomeie o arquivo ou informe --feature <slug>.`
+    );
   }
 
-  const trimmed = content.replace(/\n+$/, "");
-  return { content: `${trimmed}\n\n## ${area}\n${newLine}\n`, found: false };
+  return { destPath: `${squad}/${area}/${produto}/${fileName}`, area, fileName };
 }
 
 /**
  * @param {Object} opts
- * @param {string} opts.localFile - Caminho do arquivo local (ex: `./docs/engineering/ard-x.md`)
- * @param {string} opts.tipo - prd|frd|ard|rfc|swagger|qa-report
- * @param {string} opts.feature - Slug da feature (kebab-case)
- * @param {string} opts.squad - Squad (já resolvido pelo caller: override ou ENV.md)
- * @param {string} opts.workspace - Workspace (já resolvido pelo caller: override ou ENV.md)
- * @param {string} opts.repo - CENTRAL_DOCS_REPO
- * @param {string} [opts.targetBranch] - Branch base do MR/PR (padrão: "dev")
- * @param {string|number} [opts.cacheTtl] - TTL do cache do index.md em segundos (padrão: 3600)
- * @returns {Promise<{ sha: string, mr: { vendor: string, iid: number|string, url: string } }>}
+ * @param {Object} opts.storage - Adaptador (`getStorage`)
+ * @param {string} opts.localFile
+ * @param {string} opts.tipo
+ * @param {string} opts.squad
+ * @param {string} opts.produto
+ * @param {string} [opts.feature]
+ * @returns {Promise<{ destPath: string, indexPath: string, sha?: string, branch?: string, mr?: Object }>}
  */
-export async function publishFile(opts) {
-  const {
-    localFile,
-    tipo,
-    feature,
-    squad,
-    workspace,
-    repo,
-    targetBranch = "dev",
-    cacheTtl = "3600",
-  } = opts;
-
-  if (!repo) {
+export async function publishFile({ storage, localFile, tipo, squad, produto, feature }) {
+  if (!storage) {
     throw new Error(
-      "CENTRAL_DOCS_REPO não configurado no ENV.md\n\nConfigure a URL do repositório central:\n  CENTRAL_DOCS_REPO=https://gitlab.com/org/central-docs.git"
+      "Central docs desligado (CENTRAL_DOCS_STORAGE vazio). Configure-o no /jarvis-init."
     );
   }
 
+  const { destPath } = resolveDestPath({ tipo, squad, produto, localFile, feature });
+
   logger.info("Validando frontmatter...");
   validateFrontmatter(localFile, tipo);
   logger.info("✅ Frontmatter válido");
 
-  const metadata = extractMetadata(localFile);
-  const version = metadata.version || "1.0.0";
-  const status = metadata.status || "draft";
-  const jira = metadata.jira || "";
-  const docName = metadata.name || "";
-
-  const { destPath, area } = resolveDestPath({ tipo, squad, workspace, feature, localFile });
-  const indexPath = `${squad}/${workspace}/index.md`;
-  const branchName = `docs/${squad}/${workspace}/${tipo}-${feature}`;
-
   logger.info("");
   logger.info("📋 Resumo da Publicação:");
-  logger.info(`  Squad: ${squad}`);
-  logger.info(`  Workspace: ${workspace}`);
-  logger.info(`  Tipo: ${tipo}`);
-  logger.info(`  Feature: ${feature}`);
+  logger.info(`  Armazenamento: ${storage.kind}${storage.isGit ? " (git)" : ""}`);
   logger.info(`  Destino: ${destPath}`);
-  logger.info(`  Branch: ${branchName} → ${targetBranch}`);
   logger.info("");
 
-  const fileContentBase64 = readFileSync(localFile).toString("base64");
-
-  logger.info("Buscando index.md do workspace...");
-  let indexContent = "";
-  try {
-    indexContent = await fetchFile(indexPath, targetBranch, { repo, cacheTtl });
-  } catch {
-    indexContent = "";
-  }
+  const result = await storage.publish({ localFile, destPath, squad, tipo });
 
-  let indexAction;
-  if (!indexContent) {
-    logger.info("⚠️  index.md não encontrado, será criado");
-    indexAction = "create";
-    indexContent = `# ${workspace}\n\n**Squad:** ${squad}\n\n## ${area}\n\n`;
-  } else {
-    indexAction = "update";
+  logger.info(`✅ Publicado em ${destPath}`);
+  logger.info(`🗂️  Índice regenerado: ${result.indexPath}`);
+  if (result.mr) {
+    logger.info(`🔀 Pull/Merge Request: ${result.mr.url}`);
   }
 
-  let newLine = `- [${tipo}-${feature}.md](${area}/${tipo}-${feature}.md) | v${version} | ${status}`;
-  if (jira) newLine += ` | jira: ${jira}`;
-  if (docName) newLine += ` | ${docName}`;
-
-  const { content: updatedIndex } = insertIndexLine(indexContent, area, newLine);
-  const updatedIndexBase64 = Buffer.from(updatedIndex, "utf-8").toString("base64");
-
-  logger.info("Criando branch e commit...");
-  const commitResult = await commitFiles(repo, {
-    branch: branchName,
-    startBranch: targetBranch,
-    message: `docs(${squad}): add ${tipo} ${feature}`,
-    files: [
-      { path: destPath, contentBase64: fileContentBase64, action: "create" },
-      { path: indexPath, contentBase64: updatedIndexBase64, action: indexAction },
-    ],
-  });
-  logger.info(`✅ Commit criado: ${commitResult.sha}`);
-
-  logger.info("Criando Merge/Pull Request...");
-  let mrDescription = `## Documento\n\n- **Tipo**: ${tipo}\n- **Workspace**: ${workspace}\n- **Feature**: ${feature}`;
-  if (jira) mrDescription += `\n- **Card**: ${jira}`;
-  if (docName) mrDescription += `\n- **Nome**: ${docName}`;
-
-  const mr = await createMergeRequest(repo, {
-    source: branchName,
-    target: targetBranch,
-    title: `docs(${squad}): ${tipo} ${feature}`,
-    description: mrDescription,
-  });
-
-  logger.info("");
-  logger.info("✅ Merge/Pull Request criado com sucesso!");
-  logger.info("");
-  logger.info(`  #${mr.iid}: ${branchName} → ${targetBranch}`);
-  logger.info(`  URL: ${mr.url}`);
-  logger.info("");
-
-  redisDel(`docs:${indexPath}:${targetBranch}`);
-  redisDel(`docs:${indexPath}:main`);
-  logger.info("🔄 Cache Redis invalidado");
-  logger.info("");
-  logger.info("✅ Publicação concluída!");
-
-  return { sha: commitResult.sha, mr };
+  return result;
 }

package/bin/lib/docs/storage/build-index.js

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Gera o `{SQUAD}/index.md` do Central docs a partir do frontmatter
+ * da consolidação (funcionalidades e entregas). O índice é sempre regenerado pela listagem (nunca editado), para
+ * duas publicações seguidas não apagarem a entrada uma da outra.
+ * @module docs/storage/build-index
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { parseFrontmatter } from "../../utils/frontmatter.js";
+
+/** @constant {ReadonlyArray<string>} Áreas do Central docs, na ordem do índice */
+export const AREAS = Object.freeze(["product", "engineering"]);
+
+/**
+ * Lista arquivos (recursivo) de uma pasta, em ordem alfabética.
+ * @param {string} dir
+ * @returns {string[]} caminhos absolutos
+ */
+export function walkFiles(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .sort()
+    .flatMap((name) => {
+      const full = join(dir, name);
+      return statSync(full).isDirectory() ? walkFiles(full) : [full];
+    });
+}
+
+/** @constant {Readonly<Record<string, {prefix: string, title: string}>>} O que cada área lista no índice */
+export const INDEXED = Object.freeze({
+  product: { prefix: "feature-", title: "Funcionalidades (estado atual)" },
+  engineering: { prefix: "delivery-", title: "Entregas recentes" },
+});
+
+/** @constant {number} Entregas listadas por produto (as mais recentes; o nome começa pela data) */
+export const MAX_DELIVERIES_PER_PRODUCT = 10;
+
+/**
+ * Monta o conteúdo do índice de um squad. Lista só a consolidação do
+ * `/eng.spec-consolidate`: funcionalidades (`feature-*`) e as entregas mais recentes
+ * (`delivery-*`). Outros arquivos (ex.: PRD/ARD publicados na 4.0.0) ficam fora.
+ * Formato: `# SQUAD` › `## área` › `### produto` › `- [arquivo](caminho) | status | nome | atualizado`.
+ * @param {string} root - Pasta do Central docs
+ * @param {string} squad
+ * @returns {string}
+ */
+export function renderIndex(root, squad) {
+  const out = [`# ${squad}`, ""];
+
+  for (const area of AREAS) {
+    const { prefix, title } = INDEXED[area];
+    const areaDir = join(root, squad, area);
+    const files = walkFiles(areaDir).filter((f) => {
+      const name = f.split(sep).pop();
+      return name.startsWith(prefix) && name.endsWith(".md");
+    });
+    out.push(`## ${area}`, "", `> ${title}`, "");
+    if (files.length === 0) {
+      out.push("_Nenhum documento._", "");
+      continue;
+    }
+
+    const byProduct = new Map();
+    for (const file of files) {
+      const [product = "", ...rest] = relative(areaDir, file).split(sep);
+      if (rest.length === 0) continue; // arquivo solto na área, sem pasta de produto
+      if (!byProduct.has(product)) byProduct.set(product, []);
+      byProduct.get(product).push(file);
+    }
+
+    for (const [product, productFiles] of byProduct) {
+      const listed =
+        area === "engineering"
+          ? [...productFiles].sort().reverse().slice(0, MAX_DELIVERIES_PER_PRODUCT)
+          : productFiles;
+      out.push(`### ${product}`);
+      for (const file of listed) {
+        const rel = relative(join(root, squad), file).split(sep).join("/");
+        const name = rel.split("/").pop();
+        const meta = parseFrontmatter(readFileSync(file, "utf-8"));
+        let line = `- [${name}](${rel})`;
+        if (meta.status) line += ` | ${meta.status}`;
+        if (meta.name) line += ` | ${meta.name}`;
+        if (meta.task_key) line += ` | ${meta.task_key}`;
+        const when = meta.updated_at || meta.date;
+        if (when) line += ` | ${when}`;
+        out.push(line);
+      }
+      out.push("");
+    }
+  }
+
+  return out.join("\n").replace(/\n+$/, "\n");
+}
+
+/**
+ * Regenera e grava `{root}/{squad}/index.md`.
+ * @param {string} root - Pasta do Central docs
+ * @param {string} squad
+ * @returns {{ path: string, content: string }}
+ */
+export function buildIndex(root, squad) {
+  const content = renderIndex(root, squad);
+  const path = join(root, squad, "index.md");
+  writeFileSync(path, content);
+  return { path, content };
+}