sinapse-ai 1.15.0 → 1.17.0

package/.sinapse-ai/core/atlas/render-research-card.js

@@ -0,0 +1,164 @@
+/**
+ * Render — SINAPSE research card (PT-BR).
+ *
+ * Emits the SINAPSE framework as a case-study card in the same template as the
+ * engineering-software research corpus (domain cards + LOOPS-*-diagramas.md),
+ * fully in Portuguese. One source (the live atlas `data` + flows-pt translations)
+ * → two markdown files, so the card never drifts from how the framework actually
+ * works. Regenerated by `sinapse atlas --research-card`.
+ *
+ * Pure string builder: no fs, no Date — caller passes data.generatedAt and writes.
+ *
+ * @module core/atlas/render-research-card
+ */
+
+'use strict';
+
+const { FRAMEWORK_FLOWS_PT } = require('./flows-pt');
+
+/** Roman-numeral severity → short PT label is not needed; severity is kept verbatim. */
+
+/**
+ * Build the SINAPSE case-study card markdown (PT-BR).
+ * @param {object} data - atlas data (buildAtlasData output)
+ * @param {Record<string,object>} pt - flow id → PT translation
+ * @returns {string}
+ */
+function buildCard(data, pt) {
+  const c = data.counts;
+  const date = (data.generatedAt || '').slice(0, 10);
+  const flows = data.flows || [];
+
+  const flowList = flows
+    .map((f) => {
+      const t = pt[f.id] || { titulo: f.title, proposito: f.purpose };
+      return `- **${t.titulo}** — ${t.proposito}`;
+    })
+    .join('\n');
+
+  const articleRows = (data.articles || [])
+    .map((a) => `| ${a.number} | ${a.title} | ${a.severity} |`)
+    .join('\n');
+
+  return `---
+titulo: "SINAPSE — Framework de Engenharia Orientada por IA (estudo de caso)"
+tipo: estudo-de-caso
+dominio: sinapse-framework
+status: instancia-viva
+prioridade: alta
+created: ${date}
+gerado_por: "sinapse atlas --research-card (auto-regenerável a partir do disco)"
+---
+
+# SINAPSE — Framework de Engenharia Orientada por IA
+
+> O SINAPSE é a instância viva dos domínios desta pesquisa: um meta-framework que impõe processo (spec antes de código, gates inegociáveis, delegação a especialistas) e orquestra ${c.agentsTotal} agentes em ${c.squads} squads para construir software com rigor.
+> Este card é gerado do próprio framework (\`sinapse atlas\`), então descreve o que ele **realmente** faz hoje — não uma intenção desatualizada.
+
+## Por que este estudo de caso importa
+
+Os ${60} domínios desta pesquisa descrevem **como** construir software de qualidade com IA. O SINAPSE é uma resposta concreta a "como operacionalizar tudo isso de forma reproduzível": transforma princípios (Building Effective Agents, spec-driven development, context engineering, evals como gate) em **enforcement automático** — hooks que bloqueiam, gates que barram, orquestradores que delegam. Ler este card lado a lado com os domínios mostra a ponte entre teoria de engenharia aumentada por IA e um sistema sociotécnico em produção.
+
+## O que é o SINAPSE (números exatos, do disco)
+
+| Dimensão | Quantidade |
+|---|---:|
+| Squads | ${c.squads} |
+| Agentes (total) | ${c.agentsTotal} |
+| — de framework | ${c.frameworkAgents} |
+| — de squad | ${c.squadAgents} |
+| Orquestradores (-orqx) | ${c.orqx} |
+| Workflows | ${c.workflowsTotal} |
+| Artigos da constituição | ${c.articles} |
+| Regras ativas | ${c.rules} |
+
+## Como funciona — a cada pedido, prompt, execução e orquestração
+
+O SINAPSE é descrito por ${flows.length} meta-fluxos. Cada um é um mecanismo real do framework (não há invenção — todos rastreiam para uma regra/hook). Os diagramas em PT-BR estão em \`LOOPS-sinapse-diagramas.md\`.
+
+${flowList}
+
+## Princípios constitucionais (gates inegociáveis)
+
+A constituição tem ${c.articles} artigos. Gates automáticos bloqueiam violações.
+
+| Art. | Princípio | Severidade |
+|---|---|---|
+${articleRows}
+
+## Catálogo de workflows
+
+${c.workflowsTotal} workflows no total — ${c.frameworkWorkflows} de framework (orquestração, doc-first, greenfield/brownfield, QA) e ${c.squadWorkflows} de squad (expertise de domínio). O catálogo completo (com arquivo-fonte) vive no Atlas em \`docs/framework/atlas/OPERATING-ATLAS.md\`.
+
+## Os meta-fluxos visuais
+
+Todos os ${flows.length} diagramas Mermaid, em PT-BR, em **\`LOOPS-sinapse-diagramas.md\`** — no mesmo formato dos arquivos \`LOOPS-*-diagramas.md\` desta pesquisa.
+
+---
+
+*Card gerado por \`sinapse atlas --research-card\` em ${date}. Fonte única → não editar à mão (re-rode o gerador).*
+`;
+}
+
+/**
+ * Build the LOOPS-sinapse-diagramas markdown (PT-BR): every flow as a Mermaid block.
+ * @param {object} data - atlas data
+ * @param {Record<string,object>} pt - flow id → PT translation
+ * @returns {string}
+ */
+function buildLoops(data, pt) {
+  const date = (data.generatedAt || '').slice(0, 10);
+  const flows = data.flows || [];
+
+  const blocks = flows
+    .map((f, i) => {
+      const t = pt[f.id] || { titulo: f.title, proposito: f.purpose, mermaid: f.mermaid };
+      const mermaid = t.mermaid || f.mermaid;
+      return `## MF${i + 1} — ${t.titulo}
+
+> ${t.proposito}
+
+\`\`\`mermaid
+${mermaid}
+\`\`\`
+`;
+    })
+    .join('\n');
+
+  return `---
+titulo: "LOOPS — Meta-fluxos do SINAPSE (estudo de caso)"
+tipo: loops-diagramas
+dominio: sinapse-framework
+status: instancia-viva
+created: ${date}
+total_diagramas: ${flows.length}
+---
+
+# LOOPS — Meta-fluxos do SINAPSE
+
+> Os ${flows.length} fluxos operacionais do framework SINAPSE em Mermaid — como ele funciona a cada pedido, prompt, execução e orquestração. Renderizam direto no GitHub.
+> Gerado por \`sinapse atlas --research-card\`; fonte única no próprio framework.
+
+${blocks}
+---
+
+*Gerado em ${date}. Re-rode \`sinapse atlas --research-card\` para atualizar.*
+`;
+}
+
+/**
+ * Render both PT-BR research artifacts from atlas data.
+ * @param {object} data - atlas data (buildAtlasData output)
+ * @param {object} [opts]
+ * @param {Record<string,object>} [opts.pt] - flow translations (defaults to FRAMEWORK_FLOWS_PT)
+ * @returns {{ card: string, loops: string }}
+ */
+function renderResearchCard(data, opts = {}) {
+  const pt = opts.pt || FRAMEWORK_FLOWS_PT;
+  return {
+    card: buildCard(data, pt),
+    loops: buildLoops(data, pt),
+  };
+}
+
+module.exports = { renderResearchCard };

package/.sinapse-ai/core/orchestration/build-command.js

@@ -0,0 +1,136 @@
+/**
+ * Build Command — executable sibling of `sinapse route`.
+ *
+ * `route()` SHOWS the deterministic doc-first decision for a briefing (type →
+ * workflow → required docs → gate). `build()` RUNS it: it drives the
+ * BobOrchestrator decision-tree engine (Projeto Bob) from a briefing in GUIDED
+ * mode — it detects project state, routes to the greenfield / brownfield /
+ * existing-project handler, and surfaces the next action/checkpoint instead of
+ * spawning agents headlessly.
+ *
+ * Congruence guarantee: both `route()` and `build()` start from
+ * `resolveDocFirstState`, so the conversation, the doc-first gate hook, `route`
+ * and `build` can never disagree about type/workflow/gate.
+ *
+ * The heavy orchestration index (locks, observability panel, status writer) is
+ * required LAZILY — `--dry-run` never constructs it, so it stays side-effect-free.
+ *
+ * @module core/orchestration/build-command
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveDocFirstState } = require('./doc-first-resolver');
+
+let chalk;
+try {
+  chalk = require('chalk');
+} catch {
+  const id = (s) => s;
+  chalk = {
+    green: id, red: id, yellow: Object.assign(id, { bold: id }),
+    cyan: Object.assign(id, { bold: id }), gray: id, bold: id, dim: id,
+  };
+}
+
+/**
+ * Render the compact doc-first routing header (the "plan"), shared with `route`
+ * so `build` is visibly congruent with it.
+ * @param {string} brief
+ * @param {object} state - resolveDocFirstState() result
+ */
+function printPlanHeader(brief, state) {
+  const ok = (b) => (b ? chalk.green('✓') : chalk.red('✗'));
+  const briefLabel = brief ? `"${brief}"` : '(no brief — using project state only)';
+
+  console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════'));
+  console.log(chalk.cyan.bold('  🛠️  SINAPSE Build — guided orchestration'));
+  console.log(chalk.cyan('═══════════════════════════════════════════════════════════\n'));
+
+  console.log(`Brief:        ${chalk.gray(briefLabel)}`);
+  console.log(`Project type: ${chalk.bold(state.projectType)}`);
+  console.log(`Workflow:     ${chalk.bold(state.workflow || 'SDC (no upstream re-doc)')}`);
+  console.log(
+    `Doc-first:    ${state.gate.satisfied
+      ? chalk.green('✅ gate satisfied')
+      : chalk.red('🚫 gate blocked — missing: ' + state.gate.missing.join(', '))}\n`,
+  );
+  void ok;
+}
+
+/**
+ * Render the BobOrchestrator result in a guided, scannable way.
+ * @param {object} result - OrchestrationResult from BobOrchestrator.orchestrate
+ */
+function printEngineResult(result) {
+  const r = result || {};
+  console.log(chalk.bold('Engine decision:'));
+  console.log(`  Project state: ${chalk.bold(r.projectState || 'unknown')}`);
+  console.log(`  Action:        ${chalk.bold(r.action || 'n/a')}`);
+
+  const data = r.data || {};
+  const nextStep = r.nextStep || data.nextStep;
+  const message = data.formattedMessage || data.message || data.summary;
+  if (message) {
+    console.log('\n' + chalk.gray(String(message).trim()));
+  }
+  if (nextStep) {
+    console.log(`\n${chalk.cyan('▶ Next step:')} ${chalk.bold(nextStep)}`);
+  }
+
+  console.log('');
+  if (r.success) {
+    console.log(chalk.green.bold('  ✅ Orchestration step completed.\n'));
+  } else {
+    console.log(chalk.red.bold(`  🚫 Orchestration did not complete: ${r.error || r.action || 'unknown'}\n`));
+  }
+}
+
+/**
+ * Execute the `build` command.
+ *
+ * @param {string} brief - User briefing (e.g. "criar um site pra X")
+ * @param {Object} [options]
+ * @param {string} [options.projectRoot] - Project root path
+ * @param {string} [options.type] - Explicit project_type override
+ * @param {boolean} [options.dryRun] - Show the plan + engine entry without running it
+ * @returns {Promise<{success:boolean, exitCode:number, state:object, result?:object}>}
+ */
+async function build(brief, options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const state = resolveDocFirstState({ projectRoot, brief, projectType: options.type });
+
+  printPlanHeader(brief, state);
+
+  if (options.dryRun) {
+    console.log(chalk.yellow.bold('  (dry-run) '), 'would run BobOrchestrator.orchestrate({ userGoal })');
+    console.log(
+      chalk.gray('  No engine constructed — no locks, no panel, no side effects.\n'),
+    );
+    return { success: true, exitCode: 0, state };
+  }
+
+  // Lazily require the heavy orchestration index ONLY for the real run.
+  let BobOrchestrator;
+  try {
+    ({ BobOrchestrator } = require('./index'));
+  } catch (error) {
+    console.log(chalk.red(`  ✗ Could not load orchestration engine: ${error.message}\n`));
+    return { success: false, exitCode: 1, state };
+  }
+
+  const bob = new BobOrchestrator(projectRoot, { userGoal: brief });
+  const result = await bob.orchestrate({ userGoal: brief, storyPath: options.storyPath });
+
+  printEngineResult(result);
+
+  return {
+    success: !!(result && result.success),
+    exitCode: result && result.success === false ? 1 : 0,
+    state,
+    result,
+  };
+}
+
+module.exports = { build };

package/.sinapse-ai/core/orchestration/doc-first-resolver.js

@@ -0,0 +1,322 @@
+/**
+ * Doc-First Resolver — deterministic "what does this project need before code?"
+ *
+ * Single source of truth for the Documentation-First contract (Constitution
+ * Article III). Given a project root (and optionally a user brief), it answers,
+ * with NO LLM reasoning and NO side effects:
+ *
+ *   - projectType : site | lp | app | platform | saas | api | service | feature | fix
+ *   - workflow    : which greenfield workflow applies (reuses greenfield-handler map)
+ *   - artifacts   : the upstream docs required before stories (brief/prd/spec/arch)
+ *   - gate        : is the minimal doc-first gate satisfied? (PRD + epic + a Ready story)
+ *
+ * Two consumers share this module so they never drift:
+ *   1. `sinapse route "<brief>"` — read-only observability of the routing decision.
+ *   2. The doc-first PreToolUse gate hook — blocks code writes when `gate.satisfied`
+ *      is false. The module is intentionally dependency-light (fs/path + the
+ *      greenfield-handler constants only) so it is safe and fast to require inside
+ *      a hook. It NEVER constructs the heavy BobOrchestrator (locks, panels, etc.).
+ *
+ * @module core/orchestration/doc-first-resolver
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  GREENFIELD_WORKFLOW_BY_TYPE,
+  resolveGreenfieldWorkflow,
+} = require('./greenfield-handler');
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              PROJECT TYPE CLASSIFICATION
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Keyword → project_type map. Mirrors the classification matrix in
+ * `.claude/rules/documentation-first.md` and `project-intelligence.md`.
+ * Order matters: more specific buckets are tested before broader ones.
+ * @constant
+ */
+const TYPE_KEYWORDS = Object.freeze([
+  { type: 'fix', words: ['bug', 'conserta', 'corrige', 'corrigir', 'ajusta', 'ajustar', 'tweak', 'hotfix'] },
+  { type: 'refactor', words: ['refatora', 'refatorar', 'refactor', 'renomeia', 'renomear', 'limpa', 'cleanup'] },
+  { type: 'lp', words: ['landing page', 'landing', 'lp', 'sales page', 'captura', 'squeeze'] },
+  { type: 'saas', words: ['saas', 'software as a service', 'multi-tenant', 'multitenant'] },
+  { type: 'platform', words: ['plataforma', 'platform', 'dashboard', 'admin', 'portal', 'painel'] },
+  { type: 'app', words: ['app mobile', 'mobile', 'ios', 'android', 'react native', 'flutter', 'aplicativo'] },
+  { type: 'api', words: ['api', 'backend', 'microservice', 'microsserviço', 'rest', 'graphql'] },
+  { type: 'service', words: ['worker', 'cron', 'etl', 'integration', 'integração', 'automation', 'automação'] },
+  { type: 'site', words: ['site', 'website', 'web site', 'institucional', 'página', 'pagina'] },
+  { type: 'feature', words: ['feature', 'funcionalidade', 'implementa', 'implementar', 'adiciona'] },
+]);
+
+/** Escape a string for safe use inside a RegExp. */
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Classify a brief string into a project_type. Returns `null` when the brief is
+ * empty or no keyword matches (caller decides the fallback). Matching is by whole
+ * word/phrase boundary (so "Asaas" does NOT match the keyword "saas").
+ * @param {string} [brief]
+ * @returns {string|null}
+ */
+function classifyProjectType(brief) {
+  if (!brief || typeof brief !== 'string') return null;
+  const haystack = brief.toLowerCase();
+  for (const { type, words } of TYPE_KEYWORDS) {
+    if (words.some((w) => new RegExp(`\\b${escapeRegExp(w)}\\b`, 'i').test(haystack))) {
+      return type;
+    }
+  }
+  return null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              REQUIRED ARTIFACTS PER PROJECT TYPE
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Upstream artifacts required BEFORE the first story, keyed by greenfield
+ * workflow. Mirrors the "Required upstream artifacts per project type" table in
+ * `documentation-first.md`. `feature` / `fix` / `refactor` do not require the
+ * upstream re-doc chain (they ride on an existing project).
+ * @constant
+ */
+const REQUIRED_ARTIFACTS_BY_WORKFLOW = Object.freeze({
+  'greenfield-ui': [
+    { id: 'brief', path: 'docs/project-brief.md' },
+    { id: 'prd', path: 'docs/prd.md' },
+    { id: 'front-end-spec', path: 'docs/front-end-spec.md' },
+    { id: 'architecture', path: 'docs/front-end-architecture.md' },
+  ],
+  'greenfield-fullstack': [
+    { id: 'brief', path: 'docs/project-brief.md' },
+    { id: 'prd', path: 'docs/prd.md' },
+    { id: 'front-end-spec', path: 'docs/front-end-spec.md' },
+    { id: 'architecture', path: 'docs/fullstack-architecture.md' },
+  ],
+  'greenfield-service': [
+    { id: 'brief', path: 'docs/project-brief.md' },
+    { id: 'prd', path: 'docs/prd.md' },
+    { id: 'architecture', path: 'docs/service-architecture.md' },
+  ],
+});
+
+/** Project types that bypass the upstream greenfield doc-chain. */
+const LIGHT_TYPES = Object.freeze(['feature', 'fix', 'refactor']);
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              PROJECT MATURITY
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+/** Directories whose presence (with real files) signals existing application code. */
+const CODE_DIRS = Object.freeze(['src', 'app', 'packages', 'components', 'pages', 'lib']);
+
+/**
+ * Assess project maturity for gate scoping. Two signals matter:
+ *
+ *   - isFrameworkRepo : this IS the SINAPSE framework's own repo (package.json
+ *                       name === 'sinapse-ai'). Framework development operates
+ *                       above the story layer (Constitution Art. III exception),
+ *                       so the doc-first gate must never block it.
+ *   - isGreenfield    : the project has no substantial application code yet — a
+ *                       brand-new project. The hard doc-first gate applies HERE
+ *                       (this is the "criar um site → straight to code" case).
+ *                       Existing projects defer to the lighter story-gate.
+ *
+ * @param {string} projectRoot
+ * @returns {{ isFrameworkRepo: boolean, isGreenfield: boolean }}
+ */
+function assessProjectMaturity(projectRoot) {
+  let isFrameworkRepo = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+    if (pkg && pkg.name === 'sinapse-ai') isFrameworkRepo = true;
+  } catch {
+    // no package.json — fine
+  }
+
+  // Greenfield = no substantial application code yet. A lone package.json does
+  // NOT flip this off — otherwise scaffolding package.json first (an exempt
+  // file) would bypass the gate. Only populated code dirs count as "existing".
+  const hasCode = CODE_DIRS.some((d) => dirHasAnyFile(path.join(projectRoot, d)));
+  const isGreenfield = !hasCode;
+
+  return { isFrameworkRepo, isGreenfield };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              MINIMAL DOC-FIRST GATE
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+const VALID_STORY_STATUSES = Object.freeze(['ready', 'inprogress', 'inreview', 'done']);
+
+/** True if a `docs/prd.md` (or sharded `docs/prd/`) exists and is non-trivial. */
+function hasPrd(projectRoot) {
+  const file = path.join(projectRoot, 'docs', 'prd.md');
+  if (fileHasContent(file)) return true;
+  return dirHasMarkdown(path.join(projectRoot, 'docs', 'prd'));
+}
+
+/** True if at least one epic exists under `docs/epics/` or `docs/stories/epics/`. */
+function hasEpic(projectRoot) {
+  return (
+    dirHasMarkdown(path.join(projectRoot, 'docs', 'epics')) ||
+    dirHasMarkdown(path.join(projectRoot, 'docs', 'stories', 'epics'))
+  );
+}
+
+/** True if at least one story under `docs/stories/` is at a >= Ready status. */
+function hasReadyStory(projectRoot) {
+  const dir = path.join(projectRoot, 'docs', 'stories');
+  return walkMarkdown(dir).some((f) => storyStatusIsReady(f));
+}
+
+/**
+ * Parse a story file's frontmatter `status:` and decide whether it is >= Ready.
+ * Uses a bounded, non-greedy regex (the greedy `[\w\s]*` form historically
+ * captured the next line — see the story-gate memory).
+ * @param {string} file
+ * @returns {boolean}
+ */
+function storyStatusIsReady(file) {
+  let content;
+  try {
+    content = fs.readFileSync(file, 'utf8');
+  } catch {
+    return false;
+  }
+  const m = content.match(/status:\s*["']?([a-z][a-z ]*?)["']?\s*(?:\r?\n|$)/i);
+  if (!m) return false;
+  const status = m[1].toLowerCase().replace(/\s+/g, '');
+  return VALID_STORY_STATUSES.includes(status);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              MAIN RESOLVER
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Resolve the full doc-first picture for a project.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.projectRoot=process.cwd()] - Project root.
+ * @param {string} [opts.brief] - User briefing (used to classify project type).
+ * @param {string} [opts.projectType] - Explicit type override (skips classification).
+ * @returns {{
+ *   brief: string|null,
+ *   projectType: string,
+ *   classified: boolean,
+ *   isLightType: boolean,
+ *   workflow: string|null,
+ *   artifacts: Array<{id:string, path:string, exists:boolean}>,
+ *   gate: { prd:boolean, epic:boolean, readyStory:boolean, satisfied:boolean, missing:string[] }
+ * }}
+ */
+function resolveDocFirstState(opts = {}) {
+  const projectRoot = opts.projectRoot || process.cwd();
+  const brief = opts.brief || null;
+  const classifiedType = opts.projectType || classifyProjectType(brief);
+  const projectType = classifiedType || 'site'; // safe default: assume a full project needs docs
+  const isLightType = LIGHT_TYPES.includes(projectType);
+
+  const workflow = isLightType ? null : resolveGreenfieldWorkflow(projectType);
+
+  const artifacts = (REQUIRED_ARTIFACTS_BY_WORKFLOW[workflow] || []).map((a) => ({
+    id: a.id,
+    path: a.path,
+    exists: fileHasContent(path.join(projectRoot, a.path)),
+  }));
+
+  const prd = hasPrd(projectRoot);
+  const epic = hasEpic(projectRoot);
+  const readyStory = hasReadyStory(projectRoot);
+
+  // Light types ride on an existing project: the minimal gate is "a Ready story"
+  // (the existing story-gate). Full projects additionally need PRD + epic.
+  const missing = [];
+  if (!readyStory) missing.push('story (status >= Ready)');
+  if (!isLightType) {
+    if (!prd) missing.push('PRD (docs/prd.md)');
+    if (!epic) missing.push('epic (docs/epics/)');
+  }
+  const satisfied = missing.length === 0;
+
+  return {
+    brief,
+    projectType,
+    classified: Boolean(classifiedType),
+    isLightType,
+    workflow,
+    artifacts,
+    gate: { prd, epic, readyStory, satisfied, missing },
+    maturity: assessProjectMaturity(projectRoot),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+//                              FS HELPERS (lean, no deps)
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+function fileHasContent(file) {
+  try {
+    const stat = fs.statSync(file);
+    return stat.isFile() && stat.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+function dirHasMarkdown(dir) {
+  try {
+    return fs.readdirSync(dir).some((f) => f.toLowerCase().endsWith('.md'));
+  } catch {
+    return false;
+  }
+}
+
+/** True if `dir` exists and contains at least one regular file (any depth-1 entry). */
+function dirHasAnyFile(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true }).some((e) => e.isFile() || e.isDirectory());
+  } catch {
+    return false;
+  }
+}
+
+/** Recursively collect `.md` files under a dir (bounded depth, fail-safe). */
+function walkMarkdown(dir, depth = 0) {
+  if (depth > 4) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...walkMarkdown(full, depth + 1));
+    } else if (e.name.toLowerCase().endsWith('.md')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  classifyProjectType,
+  resolveDocFirstState,
+  assessProjectMaturity,
+  REQUIRED_ARTIFACTS_BY_WORKFLOW,
+  TYPE_KEYWORDS,
+  // re-exported for callers that want the raw map
+  GREENFIELD_WORKFLOW_BY_TYPE,
+};