agent-master-devsecops 3.9.0 → 5.1.0

package/scripts/bin/smart_onboarding.js

@@ -0,0 +1,905 @@
+#!/usr/bin/env node
+/**
+ * scripts/bin/smart_onboarding.js
+ * 
+ * Motor de Onboarding Bimodal Autônomo & Auto-Provisionamento da Tríade (Regra 16 - AGDEV-37).
+ * Detecta automaticamente se o projeto é Greenfield (novo do zero) ou Brownfield (existente),
+ * audita credenciais Atlassian, auto-provisiona Projeto no Jira e Espaço no Confluence via API (se ausentes),
+ * e publica um Portal Executivo de Arquitetura no Confluence sem jamais deixar a Homepage vazia.
+ * Implementa o Gate Compulsório da Regra 16 e exportação em padrão OASIS SARIF v2.1.0.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getAtlassianCredentials, requestAtlassian, checkGithubAuth } = require('../integrations/atlassian_client.js');
+const { createSarifReport } = require('../core/sarif_engine.js');
+
+// Diretórios e namespaces ignorados durante varreduras (imutável)
+const IGNORED_DIRS = Object.freeze(new Set([
+  '.git',
+  '.gemini',
+  '.antigravity',
+  '.vscode',
+  '.idea',
+  'node_modules',
+  'agent-master-devsecops',
+  'dist',
+  'build',
+  'target',
+  'coverage',
+  '.gradle',
+  '.mvn'
+]));
+
+// Manifestos canônicos de build e gerenciadores de dependência (imutável)
+const BUILD_MANIFESTS = Object.freeze(new Set([
+  'pom.xml',
+  'build.gradle',
+  'build.gradle.kts',
+  'package.json',
+  'go.mod',
+  'Cargo.toml',
+  'requirements.txt',
+  'pyproject.toml',
+  'Pipfile',
+  'Gemfile',
+  'composer.json',
+  'Dockerfile',
+  'docker-compose.yml',
+  'docker-compose.yaml',
+  'Makefile',
+  'CMakeLists.txt',
+  'mix.exs'
+]));
+
+// Assinaturas tecnológicas de stack declarativas e imutáveis
+const STACK_SIGNATURES = Object.freeze([
+  { manifest: 'pom.xml', stack: 'Java (Maven / Spring Boot)', hasMaven: true },
+  { manifest: 'build.gradle', stack: 'Java (Gradle)', hasGradle: true },
+  { manifest: 'build.gradle.kts', stack: 'Kotlin (Gradle Kotlin DSL)', hasGradle: true },
+  { manifest: 'package.json', stack: 'Node.js / TypeScript', hasNpm: true },
+  { manifest: 'go.mod', stack: 'Go' },
+  { manifest: 'Cargo.toml', stack: 'Rust' },
+  { manifest: 'requirements.txt', stack: 'Python' },
+  { manifest: 'pyproject.toml', stack: 'Python (Poetry / Modern)' },
+  { manifest: 'Dockerfile', stack: 'Docker', hasDocker: true },
+  { manifest: 'docker-compose.yml', stack: 'Docker Compose', hasDocker: true },
+  { manifest: 'docker-compose.yaml', stack: 'Docker Compose', hasDocker: true },
+  { manifest: 'Makefile', stack: 'C / Make / System' }
+]);
+
+/**
+ * 1. Detecção Bimodal: Greenfield vs. Brownfield com tratamento defensivo
+ * @param {string} [targetDir] 
+ * @returns {object}
+ */
+function detectProjectMode(targetDir) {
+  if (targetDir === null || (typeof targetDir !== 'string' && targetDir !== undefined)) {
+    return {
+      mode: 'GREENFIELD',
+      isBrownfield: false,
+      isGreenfield: true,
+      targetDir: targetDir || 'unknown',
+      evidence: { foundManifests: [], foundSourceDirs: [], hasReadme: false, totalRelevantEntries: 0 }
+    };
+  }
+
+  const safeTargetDir = targetDir !== undefined ? path.resolve(targetDir) : process.cwd();
+
+  if (!fs.existsSync(safeTargetDir)) {
+    return {
+      mode: 'GREENFIELD',
+      isBrownfield: false,
+      isGreenfield: true,
+      targetDir: safeTargetDir,
+      evidence: { foundManifests: [], foundSourceDirs: [], hasReadme: false, totalRelevantEntries: 0 }
+    };
+  }
+
+  let allEntries = [];
+  try {
+    allEntries = fs.readdirSync(safeTargetDir, { withFileTypes: true });
+  } catch (_) {
+    return {
+      mode: 'GREENFIELD',
+      isBrownfield: false,
+      isGreenfield: true,
+      targetDir: safeTargetDir,
+      evidence: { foundManifests: [], foundSourceDirs: [], hasReadme: false, totalRelevantEntries: 0 }
+    };
+  }
+
+  const relevantEntries = allEntries.filter(e => !IGNORED_DIRS.has(e.name));
+  const foundManifests = [];
+  const foundSourceDirs = [];
+  let hasReadme = false;
+
+  for (const entry of relevantEntries) {
+    if (entry.isFile()) {
+      if (BUILD_MANIFESTS.has(entry.name)) {
+        foundManifests.push(entry.name);
+      }
+      if (entry.name.toLowerCase() === 'readme.md') {
+        hasReadme = true;
+      }
+    } else if (entry.isDirectory()) {
+      try {
+        const subEntries = fs.readdirSync(path.join(safeTargetDir, entry.name)).filter(f => !IGNORED_DIRS.has(f));
+        if (subEntries.length > 0) {
+          foundSourceDirs.push(entry.name);
+        }
+      } catch (err) {
+        void err;
+      }
+    }
+  }
+
+  const isBrownfield = foundManifests.length > 0 || foundSourceDirs.length > 0 || (hasReadme && relevantEntries.length > 1);
+  const mode = isBrownfield ? 'BROWNFIELD' : 'GREENFIELD';
+
+  return {
+    mode,
+    isBrownfield,
+    isGreenfield: !isBrownfield,
+    targetDir: safeTargetDir,
+    evidence: {
+      foundManifests,
+      foundSourceDirs,
+      hasReadme,
+      totalRelevantEntries: relevantEntries.length
+    }
+  };
+}
+
+/**
+ * 2. Engenharia Reversa Semântica de Projetos Brownfield com tratamento defensivo
+ * @param {string} [targetDir] 
+ * @returns {object}
+ */
+function inspectProjectContext(targetDir) {
+  if (targetDir === null || (typeof targetDir !== 'string' && targetDir !== undefined)) {
+    return {
+      mode: 'GREENFIELD',
+      name: 'project',
+      title: 'PROJECT',
+      description: 'Novo projeto Greenfield em inicialização.',
+      businessDomain: 'Geral',
+      stack: ['Agnóstico / Em definição'],
+      modules: [],
+      entryPoints: [],
+      hasDocker: false
+    };
+  }
+
+  const safeTargetDir = targetDir !== undefined ? path.resolve(targetDir) : process.cwd();
+
+  if (!fs.existsSync(safeTargetDir)) {
+    return {
+      mode: 'GREENFIELD',
+      name: path.basename(safeTargetDir) || 'project',
+      title: (path.basename(safeTargetDir) || 'PROJECT').toUpperCase(),
+      description: 'Novo projeto Greenfield em inicialização.',
+      businessDomain: 'Geral',
+      stack: ['Agnóstico / Em definição'],
+      modules: [],
+      entryPoints: [],
+      hasDocker: false
+    };
+  }
+
+  const detection = detectProjectMode(safeTargetDir);
+  const info = {
+    mode: detection.mode,
+    name: path.basename(safeTargetDir) || 'project',
+    title: '',
+    description: '',
+    businessDomain: 'Geral / Engenharia de Software',
+    stack: [],
+    modules: [],
+    entryPoints: [],
+    hasDocker: false
+  };
+
+  // Leitura segura do README
+  const readmePath = path.join(safeTargetDir, 'README.md');
+  if (fs.existsSync(readmePath)) {
+    try {
+      const readmeText = fs.readFileSync(readmePath, 'utf8');
+      const lines = readmeText.split(/\r?\n/).filter(Boolean);
+      for (const line of lines) {
+        if (!info.title && line.startsWith('# ')) {
+          info.title = line.replace(/^#\s+/, '').trim();
+        } else if (!info.description && !line.startsWith('#') && !line.startsWith('>')) {
+          info.description = line.trim();
+        }
+      }
+    } catch (err) {
+      void err;
+    }
+  }
+
+  if (!info.title) info.title = info.name.replace(/[-_]/g, ' ').toUpperCase();
+  if (!info.description) info.description = 'Ecossistema de software governado pelo Agent Master DevSecOps.';
+
+  // Mapeamento declarativo de Stack e Módulos
+  let entries = [];
+  try {
+    entries = fs.readdirSync(safeTargetDir, { withFileTypes: true }).filter(e => !IGNORED_DIRS.has(e.name));
+  } catch (_) {
+    entries = [];
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(safeTargetDir, entry.name);
+    if (entry.isDirectory()) {
+      try {
+        const subFiles = fs.readdirSync(fullPath);
+        const hasModuleSign = subFiles.some(f => ['pom.xml', 'package.json', 'Dockerfile', 'src', 'go.mod', 'Cargo.toml'].includes(f));
+        if (hasModuleSign) {
+          info.modules.push({
+            name: entry.name,
+            hasDocker: subFiles.includes('Dockerfile'),
+            hasMaven: subFiles.includes('pom.xml'),
+            hasNpm: subFiles.includes('package.json')
+          });
+        }
+      } catch (err) {
+        void err;
+      }
+    } else if (entry.isFile()) {
+      const sig = STACK_SIGNATURES.find(s => s.manifest === entry.name);
+      if (sig) {
+        info.stack.push(sig.stack);
+        if (sig.hasDocker) info.hasDocker = true;
+      }
+    }
+  }
+
+  if (info.modules.some(m => m.hasMaven)) info.stack.push('Java / Spring Boot');
+  if (info.modules.some(m => m.hasNpm)) info.stack.push('Node.js');
+  if (info.modules.some(m => m.hasDocker)) info.hasDocker = true;
+
+  info.stack = Array.from(new Set(info.stack));
+  if (info.stack.length === 0) info.stack.push('Agnóstico / Em definição');
+
+  return info;
+}
+
+/**
+ * 3. Auto-Provisionamento do Projeto no Jira via API oficial
+ * @param {object} creds 
+ * @param {string} projectKey 
+ * @param {string} [projectName='DevSecOps Project'] 
+ * @returns {Promise<object>}
+ */
+async function ensureJiraProject(creds, projectKey, projectName = 'DevSecOps Project') {
+  if (!creds || !creds.isConfigured) {
+    return { status: 'SKIPPED', reason: 'Credenciais Atlassian ausentes ou incompletas.' };
+  }
+
+  const cleanKey = String(projectKey || 'PROJ').toUpperCase().replace(/[^A-Z0-9]/g, '').slice(0, 10);
+  
+  // 1. Verifica se já existe
+  const checkRes = await requestAtlassian(creds, 'GET', `/rest/api/3/project/${cleanKey}`);
+  if (checkRes.status === 200) {
+    return {
+      status: 'EXISTS',
+      created: false,
+      key: cleanKey,
+      id: checkRes.body?.id,
+      name: checkRes.body?.name
+    };
+  }
+
+  // 2. Se não existir (404), obtém o accountId do líder
+  const myselfRes = await requestAtlassian(creds, 'GET', '/rest/api/3/myself');
+  const leadAccountId = myselfRes.body?.accountId;
+
+  if (!leadAccountId) {
+    return { status: 'FAILED', reason: 'Não foi possível recuperar o accountId do usuário líder.' };
+  }
+
+  const payload = {
+    key: cleanKey,
+    name: projectName,
+    projectTypeKey: 'software',
+    projectTemplateKey: 'com.pyxis.greenhopper.jira:gh-simplified-scrum-classic',
+    description: `Projeto ${projectName} criado automaticamente pelo Agent Master DevSecOps (Regra 16).`,
+    leadAccountId,
+    assigneeType: 'PROJECT_LEAD'
+  };
+
+  const createRes = await requestAtlassian(creds, 'POST', '/rest/api/3/project', payload);
+  if (createRes.status === 200 || createRes.status === 201) {
+    return {
+      status: 'CREATED',
+      created: true,
+      key: cleanKey,
+      id: createRes.body?.id,
+      name: projectName
+    };
+  }
+
+  return { status: 'FAILED', httpStatus: createRes.status, error: createRes.body };
+}
+
+/**
+ * 4. Auto-Provisionamento do Espaço no Confluence via API oficial
+ * @param {object} creds 
+ * @param {string} spaceKey 
+ * @param {string} [spaceName='DevSecOps Documentation'] 
+ * @returns {Promise<object>}
+ */
+async function ensureConfluenceSpace(creds, spaceKey, spaceName = 'DevSecOps Documentation') {
+  if (!creds || !creds.isConfigured) {
+    return { status: 'SKIPPED', reason: 'Credenciais Atlassian ausentes ou incompletas.' };
+  }
+
+  const cleanKey = String(spaceKey || 'PROJ').toUpperCase().replace(/[^A-Z0-9]/g, '').slice(0, 10);
+
+  // 1. Verifica se já existe
+  const checkRes = await requestAtlassian(creds, 'GET', `/wiki/rest/api/space/${cleanKey}`);
+  if (checkRes.status === 200) {
+    const hpId = checkRes.body?.homepage?.id || checkRes.body?.homepageId;
+    return {
+      status: 'EXISTS',
+      created: false,
+      key: cleanKey,
+      name: checkRes.body?.name,
+      homepageId: hpId
+    };
+  }
+
+  // 2. Se não existir, cria o espaço
+  const payload = {
+    key: cleanKey,
+    name: spaceName,
+    description: {
+      plain: {
+        value: `Espaço de Documentação Técnica e Arquitetura do projeto ${spaceName} governado pelo Agent Master DevSecOps.`,
+        representation: 'plain'
+      }
+    }
+  };
+
+  const createRes = await requestAtlassian(creds, 'POST', '/wiki/rest/api/space', payload);
+  if (createRes.status === 200 || createRes.status === 201) {
+    const hpId = createRes.body?.homepage?.id || createRes.body?.homepageId;
+    return {
+      status: 'CREATED',
+      created: true,
+      key: cleanKey,
+      name: spaceName,
+      homepageId: hpId
+    };
+  }
+
+  return { status: 'FAILED', httpStatus: createRes.status, error: createRes.body };
+}
+
+/**
+ * 5. Publicação do Portal Executivo na Homepage (Zero Páginas Vazias)
+ * @param {object} creds 
+ * @param {string} spaceKey 
+ * @param {string} homepageId 
+ * @param {object} projectContext 
+ * @returns {Promise<object>}
+ */
+async function publishExecutiveHomepage(creds, spaceKey, homepageId, projectContext = {}) {
+  if (!creds || !creds.isConfigured || !homepageId) {
+    return { status: 'SKIPPED', reason: 'Homepage ID ou credenciais ausentes.' };
+  }
+
+  const safeContext = {
+    title: projectContext.title || 'Sistema Enterprise',
+    description: projectContext.description || 'Ecossistema governado por agentes autônomos.',
+    mode: projectContext.mode || 'BROWNFIELD',
+    stack: Array.isArray(projectContext.stack) ? projectContext.stack : ['Nativo'],
+    modules: Array.isArray(projectContext.modules) ? projectContext.modules : []
+  };
+
+  // Recupera versão atual
+  const getRes = await requestAtlassian(creds, 'GET', `/wiki/rest/api/content/${homepageId}?expand=version`);
+  const currentVersion = getRes.body?.version?.number || 1;
+  const nextVersion = currentVersion + 1;
+
+  const stackHtml = safeContext.stack.map(s => `<li>${s}</li>`).join('');
+  const modulesHtml = safeContext.modules.length > 0
+    ? safeContext.modules.map(m => `<tr><td><code>${m.name}</code></td><td>${m.hasDocker ? 'Sim (Container)' : 'Aplicação'}</td><td>${m.hasMaven ? 'Maven' : (m.hasNpm ? 'NPM' : 'Nativo')}</td></tr>`).join('')
+    : '<tr><td><code>raiz</code></td><td>Aplicação Principal</td><td>Nativo</td></tr>';
+
+  const html = `
+    <h2>🏛️ Portal de Engenharia & Arquitetura — ${safeContext.title}</h2>
+    <p><strong>Status de Operação:</strong> Homologado sob Governança Multi-Agente Prescritiva (Regra 16).</p>
+    <p>${safeContext.description}</p>
+    <hr />
+    <h3>📌 Estrutura Canônica de Documentação (Tríade Viva)</h3>
+    <table>
+      <thead>
+        <tr>
+          <th>Seção de Documentação</th>
+          <th>Propósito de Governança</th>
+          <th>Padrão de Registro</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td><strong>🏛️ Decisões de Arquitetura (ADRs)</strong></td>
+          <td>Histórico imutável de decisões técnicas, trade-offs e racional econômico.</td>
+          <td>ADR-001 em diante</td>
+        </tr>
+        <tr>
+          <td><strong>📐 Especificações Técnicas (SPECs)</strong></td>
+          <td>Contratos públicos de API, modelos de dados, endpoints e DTOs.</td>
+          <td>SPEC-001 em diante</td>
+        </tr>
+        <tr>
+          <td><strong>🛡️ Governança & Padrões Multiagente</strong></td>
+          <td>Guias operacionais locais, esteiras CI/CD, Docker e Regras de Engenharia.</td>
+          <td>GOV-001 em diante</td>
+        </tr>
+      </tbody>
+    </table>
+    <hr />
+    <h3>🚀 Topologia Técnica do Projeto (${safeContext.mode})</h3>
+    <p><strong>Stack Tecnológica Identificada:</strong></p>
+    <ul>${stackHtml}</ul>
+    <p><strong>Módulos e Componentes Arquiteturais:</strong></p>
+    <table>
+      <thead>
+        <tr>
+          <th>Módulo</th>
+          <th>Tipo</th>
+          <th>Gerenciador de Build</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${modulesHtml}
+      </tbody>
+    </table>
+    <hr />
+    <p><em>Página gerada e mantida autonomamente pelo Agent Master DevSecOps em conformidade com a Regra 16.</em></p>
+  `;
+
+  const updatePayload = {
+    version: { number: nextVersion },
+    title: `${safeContext.title} — Portal de Engenharia`,
+    type: 'page',
+    body: {
+      storage: {
+        value: html,
+        representation: 'storage'
+      }
+    }
+  };
+
+  const putRes = await requestAtlassian(creds, 'PUT', `/wiki/rest/api/content/${homepageId}`, updatePayload);
+  return {
+    status: putRes.status === 200 ? 'SUCCESS' : 'FAILED',
+    httpStatus: putRes.status,
+    homepageId,
+    version: nextVersion
+  };
+}
+
+/**
+ * 6. Orquestrador do Onboarding Inteligente
+ * @param {string} [targetDir=process.cwd()] 
+ * @param {object} [options={}] 
+ * @returns {Promise<object>}
+ */
+async function runSmartOnboarding(targetDir = process.cwd(), options = {}) {
+  const safeTargetDir = (typeof targetDir === 'string' && targetDir) ? path.resolve(targetDir) : process.cwd();
+  const projectContext = inspectProjectContext(safeTargetDir);
+  const creds = getAtlassianCredentials(safeTargetDir);
+
+  const defaultKey = (process.env.JIRA_PROJECT_KEY || process.env.CONFLUENCE_SPACE_KEY || projectContext.name.toUpperCase().replace(/[^A-Z0-9]/g, '').slice(0, 6) || 'PROJ');
+
+  const report = {
+    targetDir: safeTargetDir,
+    mode: projectContext.mode,
+    projectContext,
+    credentialsConfigured: creds.isConfigured,
+    jira: { key: defaultKey, status: 'PENDING' },
+    confluence: { key: defaultKey, status: 'PENDING' },
+    homepage: { status: 'PENDING' }
+  };
+
+  if (!creds.isConfigured) {
+    report.jira.status = 'SKIPPED_NO_CREDENTIALS';
+    report.confluence.status = 'SKIPPED_NO_CREDENTIALS';
+    report.homepage.status = 'SKIPPED_NO_CREDENTIALS';
+    return report;
+  }
+
+  // Auto-provisiona Jira
+  const jiraRes = await ensureJiraProject(creds, defaultKey, `${projectContext.title} DevSecOps`);
+  report.jira = { ...jiraRes, key: defaultKey };
+
+  // Auto-provisiona Confluence
+  const confRes = await ensureConfluenceSpace(creds, defaultKey, `${projectContext.title} DevSecOps`);
+  report.confluence = { ...confRes, key: defaultKey };
+
+  // Popula Homepage (Zero Páginas Vazias)
+  if (confRes.homepageId) {
+    const hpRes = await publishExecutiveHomepage(creds, defaultKey, confRes.homepageId, projectContext);
+    report.homepage = hpRes;
+  }
+
+  return report;
+}
+
+/**
+ * Constrói o veredito e mensagem canônica de bloqueio ou liberação (DRY).
+ * @param {string[]} blockers 
+ * @param {object} options 
+ * @returns {object}
+ */
+function buildTriadVerdict(blockers, options = {}) {
+  const isOffline = Boolean(options.offlineMode || process.env.OFFLINE_MODE === 'true');
+  const canDevelop = options.forcePermit ? true : (isOffline ? true : blockers.length === 0);
+  const verdict = canDevelop ? (isOffline && blockers.length > 0 ? 'MODO_LOCAL_OFFLINE' : 'LIBERADO') : 'BLOQUEADO_REGRA_16';
+
+  let gateMessage = '';
+  if (!canDevelop) {
+    gateMessage = `⛔ [GATE DE GOVERNANÇA BLOQUEADO — REGRA 16]\n` +
+      `O desenvolvimento de software (criação de código, endpoints ou refatoração) está ESTRITAMENTE BLOQUEADO.\n` +
+      `O Roteiro Inicial de certificação da Tríade (Git + Jira + Confluence) ainda não foi concluído:\n` +
+      blockers.map(b => `- ${b}`).join('\n') +
+      `\n\n👉 Ação Prescrita Obrigatória: Execute "node agent-master-devsecops/scripts/bin/bootstrap_cli.js" ou configure seu .env e autentique a Tríade antes de iniciar o desenvolvimento.\n` +
+      `💡 Dica de Resiliência: Para prosseguir em modo local desacoplado sem travas, ative options.offlineMode ou a flag --offline.`;
+  } else if (verdict === 'MODO_LOCAL_OFFLINE') {
+    gateMessage = `⚡ [GATE DE GOVERNANÇA: MODO LOCAL DESACOPLADO (OFFLINE)]\n` +
+      `Credenciais externas da Atlassian ausentes, mas o desenvolvimento local foi AUTORIZADO em modo offline-first.\n` +
+      `As alterações serão registradas no Git e em docs/CHANGELOG.md para posterior sincronização.`;
+  } else {
+    gateMessage = `✅ [GATE DE GOVERNANÇA LIBERADO — REGRA 16]\n` +
+      `Tríade (Git + Jira + Confluence) 100% verificada, autêntica e operando sem falhas. Desenvolvimento de software autorizado!`;
+  }
+
+  return { canDevelop, verdict, gateMessage };
+}
+
+/**
+ * 7. Gate Compulsório da Regra 16 (Versão Síncrona)
+ * Veta comandos de desenvolvimento enquanto a Tríade (Git + Jira + Confluence)
+ * não estiver 100% configurada ou em modo offline-first.
+ * @param {string} [targetDir=process.cwd()] 
+ * @param {object} [options={}] 
+ * @returns {object}
+ */
+function verifyTriadGateSync(targetDir = process.cwd(), options = {}) {
+  const safeTargetDir = (typeof targetDir === 'string' && targetDir) ? path.resolve(targetDir) : process.cwd();
+  const gh = checkGithubAuth();
+  const creds = getAtlassianCredentials(safeTargetDir);
+  const projectContext = inspectProjectContext(safeTargetDir);
+
+  const blockers = [];
+  const defaultKey = process.env.JIRA_PROJECT_KEY || process.env.CONFLUENCE_SPACE_KEY || 'PROJ';
+
+  const isGhAuth = options.mockGithubAuthenticated !== undefined ? Boolean(options.mockGithubAuthenticated) : Boolean(gh.isAuthenticated);
+  const isAtlassianConfig = options.mockAtlassianConfigured !== undefined ? Boolean(options.mockAtlassianConfigured) : Boolean(creds.isConfigured);
+
+  const status = {
+    git: {
+      ready: isGhAuth,
+      user: gh.user || null,
+      details: gh.details || ''
+    },
+    jira: {
+      configured: isAtlassianConfig,
+      key: defaultKey,
+      projectExists: Boolean(options.mockJiraExists)
+    },
+    confluence: {
+      configured: isAtlassianConfig,
+      key: defaultKey,
+      spaceExists: Boolean(options.mockConfluenceExists),
+      homepageReady: Boolean(options.mockHomepageReady)
+    }
+  };
+
+  // 1. Checa Git / GitHub CLI
+  if (!isGhAuth) {
+    blockers.push('GitHub CLI não autenticado. Execute "gh auth login" no terminal.');
+  }
+
+  // 2. Checa Credenciais Atlassian
+  if (!isAtlassianConfig) {
+    blockers.push('Credenciais Atlassian (ATLASSIAN_DOMAIN, ATLASSIAN_EMAIL, ATLASSIAN_API_TOKEN) não configuradas no .env.');
+  }
+
+  const { canDevelop, verdict, gateMessage } = buildTriadVerdict(blockers, options);
+
+  return {
+    canDevelop,
+    verdict,
+    gateMessage,
+    blockers,
+    status,
+    projectContext
+  };
+}
+
+/**
+ * 8. Gate Compulsório da Regra 16 (Versão Assíncrona com Verificação de Rede)
+ * @param {string} [targetDir=process.cwd()] 
+ * @param {object} [options={}] 
+ * @returns {Promise<object>}
+ */
+async function verifyTriadGate(targetDir = process.cwd(), options = {}) {
+  const safeTargetDir = (typeof targetDir === 'string' && targetDir) ? path.resolve(targetDir) : process.cwd();
+  const gh = checkGithubAuth();
+  const creds = getAtlassianCredentials(safeTargetDir);
+  const projectContext = inspectProjectContext(safeTargetDir);
+
+  const blockers = [];
+  const defaultKey = process.env.JIRA_PROJECT_KEY || process.env.CONFLUENCE_SPACE_KEY || 'PROJ';
+
+  const isGhAuth = options.mockGithubAuthenticated !== undefined ? Boolean(options.mockGithubAuthenticated) : Boolean(gh.isAuthenticated);
+  const isAtlassianConfig = options.mockAtlassianConfigured !== undefined ? Boolean(options.mockAtlassianConfigured) : Boolean(creds.isConfigured);
+
+  const status = {
+    git: {
+      ready: isGhAuth,
+      user: gh.user || null,
+      details: gh.details || ''
+    },
+    jira: {
+      configured: isAtlassianConfig,
+      key: defaultKey,
+      projectExists: false
+    },
+    confluence: {
+      configured: isAtlassianConfig,
+      key: defaultKey,
+      spaceExists: false,
+      homepageReady: false
+    }
+  };
+
+  // 1. Checa Git / GitHub CLI
+  if (!isGhAuth) {
+    blockers.push('GitHub CLI não autenticado. Execute "gh auth login" no terminal.');
+  }
+
+  // 2. Checa Credenciais Atlassian
+  if (!isAtlassianConfig) {
+    blockers.push('Credenciais Atlassian (ATLASSIAN_DOMAIN, ATLASSIAN_EMAIL, ATLASSIAN_API_TOKEN) não configuradas no .env.');
+  }
+
+  // 3. Se credenciais estiverem ok, valida Jira e Confluence via API
+  if (isAtlassianConfig && !options.skipNetwork) {
+    try {
+      const jiraRes = await requestAtlassian(creds, 'GET', `/rest/api/3/project/${defaultKey}`);
+      status.jira.projectExists = (jiraRes.status === 200);
+      if (!status.jira.projectExists) {
+        blockers.push(`Projeto Jira "${defaultKey}" não encontrado na nuvem.`);
+      }
+    } catch (_) {
+      blockers.push('Falha na comunicação de rede com o Jira Cloud.');
+    }
+
+    try {
+      const confRes = await requestAtlassian(creds, 'GET', `/wiki/rest/api/space/${defaultKey}`);
+      status.confluence.spaceExists = (confRes.status === 200);
+      if (!status.confluence.spaceExists) {
+        blockers.push(`Espaço Confluence "${defaultKey}" não encontrado na nuvem.`);
+      } else {
+        const hpId = confRes.body?.homepage?.id || confRes.body?.homepageId;
+        status.confluence.homepageReady = Boolean(hpId);
+      }
+    } catch (_) {
+      blockers.push('Falha na comunicação de rede com o Confluence Cloud.');
+    }
+  }
+
+  const { canDevelop, verdict, gateMessage } = buildTriadVerdict(blockers, options);
+
+  return {
+    canDevelop,
+    verdict,
+    gateMessage,
+    blockers,
+    status,
+    projectContext
+  };
+}
+
+/**
+ * 9. Formata relatório executivo em Markdown do onboarding.
+ * @param {object} report 
+ * @returns {string}
+ */
+function formatReport(report) {
+  if (!report || typeof report !== 'object') {
+    return '# 🏛️ Agent-Master DevSecOps — Smart Onboarding Report\n\nNenhum relatório de onboarding disponível.';
+  }
+
+  let output = '# 🏛️ Agent-Master DevSecOps — Smart Onboarding Report\n\n';
+  output += `**Modo Detectado (Regra 16):** \`${report.mode || 'UNKNOWN'}\`\n`;
+  output += `**Diretório Alvo:** \`${report.targetDir || 'N/A'}\`\n`;
+  if (report.projectContext) {
+    output += `**Projeto:** ${report.projectContext.title || 'N/A'}\n`;
+    output += `**Stack Mapeada:** ${(report.projectContext.stack || []).join(', ') || 'Nativa'}\n`;
+  }
+  output += `**Credenciais Configuradas:** ${report.credentialsConfigured ? 'SIM' : 'NÃO (Modo Offline / Pendente)'}\n\n`;
+
+  output += '### 🎯 Status da Tríade de Governança\n';
+  if (report.jira) {
+    output += `- **Jira Cloud:** [${report.jira.key || 'N/A'}] -> \`${report.jira.status || 'PENDING'}\`\n`;
+  }
+  if (report.confluence) {
+    output += `- **Confluence Cloud:** [${report.confluence.key || 'N/A'}] -> \`${report.confluence.status || 'PENDING'}\`\n`;
+  }
+  if (report.homepage) {
+    output += `- **Homepage de Arquitetura:** \`${report.homepage.status || 'PENDING'}\` (Zero Páginas Vazias)\n`;
+  }
+
+  return output;
+}
+
+/**
+ * 10. Exporta o status do Gate da Tríade no formato oficial OASIS SARIF v2.1.0.
+ * @param {string} [targetDir=process.cwd()] 
+ * @param {object} [options={}] 
+ * @returns {object} SARIF v2.1.0
+ */
+function auditTriadToSarif(targetDir = process.cwd(), options = {}) {
+  const gateRes = verifyTriadGateSync(targetDir, options);
+  const findings = [];
+
+  for (const blocker of gateRes.blockers) {
+    let ruleId = 'REGRA-16-TRIAD-GATE';
+    let name = 'Violação de Gate da Tríade';
+    if (blocker.includes('GitHub')) {
+      ruleId = 'REGRA-16-GIT-AUTH';
+      name = 'GitHub CLI Não Autenticado';
+    } else if (blocker.includes('Atlassian') || blocker.includes('.env')) {
+      ruleId = 'REGRA-16-ATLASSIAN-CREDENTIALS';
+      name = 'Credenciais Atlassian Ausentes';
+    } else if (blocker.includes('Jira')) {
+      ruleId = 'REGRA-16-JIRA-PROJECT';
+      name = 'Projeto Jira Inexistente';
+    } else if (blocker.includes('Confluence')) {
+      ruleId = 'REGRA-16-CONFLUENCE-SPACE';
+      name = 'Espaço Confluence Inexistente';
+    }
+
+    findings.push({
+      ruleId,
+      name,
+      severity: 'HIGH',
+      message: blocker,
+      filename: path.join(gateRes.projectContext?.name || 'repo', '.env').replace(/\\/g, '/'),
+      line: 1,
+      column: 1
+    });
+  }
+
+  const rules = [
+    {
+      id: 'REGRA-16-GIT-AUTH',
+      name: 'GitHub CLI Não Autenticado',
+      severity: 'HIGH',
+      description: 'A Regra 16 exige rastreabilidade no Git antes de liberar o desenvolvimento de software.',
+      remediation: 'Execute "gh auth login" no terminal para autenticar sua conta.'
+    },
+    {
+      id: 'REGRA-16-ATLASSIAN-CREDENTIALS',
+      name: 'Credenciais Atlassian Ausentes',
+      severity: 'HIGH',
+      description: 'A Regra 16 exige sincronização viva com Jira e Confluence.',
+      remediation: 'Configure ATLASSIAN_DOMAIN, ATLASSIAN_EMAIL e ATLASSIAN_API_TOKEN no arquivo .env.'
+    },
+    {
+      id: 'REGRA-16-JIRA-PROJECT',
+      name: 'Projeto Jira Inexistente',
+      severity: 'HIGH',
+      description: 'O projeto Jira deve existir e estar vinculado para emissão de tickets.',
+      remediation: 'Provisione o projeto executando o comando agent-master-init ou crie-o no Jira.'
+    },
+    {
+      id: 'REGRA-16-CONFLUENCE-SPACE',
+      name: 'Espaço Confluence Inexistente',
+      severity: 'HIGH',
+      description: 'O espaço Confluence deve hospedar a documentação viva e o portal executivo.',
+      remediation: 'Provisione o espaço com homepage executiva via agent-onboard.'
+    }
+  ];
+
+  return createSarifReport({
+    toolName: 'agent-master-smart-onboarding',
+    toolVersion: '5.1.0',
+    rules,
+    findings,
+    properties: {
+      category: 'Governance Triad Gate',
+      verdict: gateRes.verdict,
+      canDevelop: gateRes.canDevelop
+    }
+  });
+}
+
+/**
+ * Classe Canônica SmartOnboarding
+ */
+class SmartOnboarding {
+  static get IGNORED_DIRS() {
+    return IGNORED_DIRS;
+  }
+
+  static get BUILD_MANIFESTS() {
+    return BUILD_MANIFESTS;
+  }
+
+  static get STACK_SIGNATURES() {
+    return STACK_SIGNATURES;
+  }
+
+  constructor(options = {}) {
+    const safeOptions = (options && typeof options === 'object') ? options : {};
+    this.targetDir = path.resolve(safeOptions.targetDir || process.cwd());
+    this.options = Object.freeze({ ...safeOptions });
+  }
+
+  detectMode(targetDir = this.targetDir) {
+    return detectProjectMode(targetDir);
+  }
+
+  inspectContext(targetDir = this.targetDir) {
+    return inspectProjectContext(targetDir);
+  }
+
+  async runOnboarding(targetDir = this.targetDir, options = this.options) {
+    return runSmartOnboarding(targetDir, options);
+  }
+
+  verifyTriadGateSync(targetDir = this.targetDir, options = this.options) {
+    return verifyTriadGateSync(targetDir, options);
+  }
+
+  async verifyTriadGate(targetDir = this.targetDir, options = this.options) {
+    return verifyTriadGate(targetDir, options);
+  }
+
+  auditTriadToSarif(targetDir = this.targetDir, options = this.options) {
+    return auditTriadToSarif(targetDir, options);
+  }
+
+  formatReport(report) {
+    return formatReport(report);
+  }
+}
+
+if (require.main === module) {
+  console.log('\n================================================================');
+  console.log('⚡ AGENT MASTER DEVSECOPS — ONBOARDING BIMODAL & AUTO-PROVISIONING');
+  console.log('================================================================\n');
+
+  runSmartOnboarding().then(report => {
+    console.log(formatReport(report));
+  }).catch(err => {
+    console.error('Erro no onboarding:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  SmartOnboarding,
+  verifyTriadGate,
+  verifyTriadGateSync,
+  detectProjectMode,
+  inspectProjectContext,
+  ensureJiraProject,
+  ensureConfluenceSpace,
+  publishExecutiveHomepage,
+  runSmartOnboarding,
+  formatReport,
+  auditTriadToSarif,
+  IGNORED_DIRS,
+  BUILD_MANIFESTS,
+  STACK_SIGNATURES
+};