trackfw 2.16.0 → 3.1.0

package/src/forge/adapter.js

@@ -0,0 +1,189 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Verificação de disponibilidade de CLI — scan puro no PATH sem subprocess
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica se um executável está disponível no PATH, respeitando
+ * TRACKFW_DISABLE_EXTERNAL_COMMANDS (mesmo padrão de discover.go).
+ * @param {string} name
+ * @returns {boolean}
+ */
+function _defaultAvailFn(name) {
+  if (!name) return false;
+  if (process.env.TRACKFW_DISABLE_EXTERNAL_COMMANDS === '1') return false;
+
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const isWindows = process.platform === 'win32';
+  const exts = isWindows
+    ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
+    : [''];
+
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      try {
+        const candidate = path.join(dir, name + ext);
+        fs.accessSync(candidate, fs.constants.F_OK | fs.constants.X_OK);
+        return true;
+      } catch (_) {
+        // continua
+      }
+    }
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Conversão de remote URL → base HTTPS
+// ---------------------------------------------------------------------------
+
+/**
+ * Converte qualquer formato de remote git (git@, ssh://, https://, http://)
+ * para URL base HTTPS sem .git.
+ *
+ * Normalização especial para Azure SSH:
+ *   git@ssh.dev.azure.com:v3/org/project/repo → https://dev.azure.com/org/project/_git/repo
+ *
+ * @param {string} rawURL
+ * @param {string} forge
+ * @returns {string}
+ */
+function remoteHTTPSBase(rawURL, forge) {
+  if (!rawURL) return '';
+  rawURL = rawURL.trim();
+  if (!rawURL) return '';
+
+  let host = '';
+  let pathStr = '';
+
+  if (rawURL.startsWith('git@')) {
+    // git@host:path
+    const rest = rawURL.slice(4);
+    const colonIdx = rest.indexOf(':');
+    if (colonIdx < 0) return '';
+    host = rest.slice(0, colonIdx).toLowerCase();
+    pathStr = rest.slice(colonIdx + 1);
+
+  } else if (rawURL.startsWith('ssh://')) {
+    // ssh://[user@]host/path
+    let rest = rawURL.slice(6);
+    const atIdx = rest.indexOf('@');
+    if (atIdx >= 0) rest = rest.slice(atIdx + 1);
+    const slashIdx = rest.indexOf('/');
+    if (slashIdx < 0) {
+      host = rest.toLowerCase();
+    } else {
+      host = rest.slice(0, slashIdx).toLowerCase();
+      pathStr = rest.slice(slashIdx + 1);
+    }
+
+  } else if (rawURL.startsWith('https://') || rawURL.startsWith('http://')) {
+    let rest = rawURL.replace(/^https?:\/\//, '');
+    const atIdx = rest.indexOf('@');
+    if (atIdx >= 0) rest = rest.slice(atIdx + 1);
+    const slashIdx = rest.indexOf('/');
+    if (slashIdx < 0) {
+      host = rest.toLowerCase();
+    } else {
+      host = rest.slice(0, slashIdx).toLowerCase();
+      pathStr = rest.slice(slashIdx + 1);
+    }
+
+  } else {
+    return '';
+  }
+
+  pathStr = pathStr.replace(/\.git$/, '').replace(/^\/|\/$/g, '');
+
+  // Normalização Azure SSH
+  if (forge === 'azure' && host === 'ssh.dev.azure.com') {
+    host = 'dev.azure.com';
+    pathStr = pathStr.replace(/^v3\//, '');
+    const parts = pathStr.split('/');
+    if (parts.length === 3) {
+      pathStr = `${parts[0]}/${parts[1]}/_git/${parts[2]}`;
+    }
+  }
+
+  if (!pathStr) return `https://${host}`;
+  return `https://${host}/${pathStr}`;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} Adapter
+ * @property {string} forge
+ * @property {string} noun        - "Pull Request" ou "Merge Request"
+ * @property {string} cliName     - nome do executável (vazio = sem CLI)
+ * @property {string[]} cliArgs   - argumentos para criar PR/MR
+ * @property {boolean} available  - false quando CLI ausente
+ * @property {function(string, string): string} fallbackURL
+ */
+
+/**
+ * Retorna o Adapter para o forge informado.
+ *
+ * @param {string} forge
+ * @param {function(string): boolean} [availFn]  - injeta verificação de CLI (para testes)
+ * @returns {Adapter}
+ */
+function forgeAdapter(forge, availFn) {
+  if (typeof availFn !== 'function') {
+    availFn = _defaultAvailFn;
+  }
+
+  let noun = 'Pull Request';
+  let cliName = '';
+  let cliArgs = [];
+  let available = false;
+
+  switch (forge) {
+    case 'github':
+      cliName = 'gh';
+      cliArgs = ['pr', 'create'];
+      available = availFn('gh');
+      break;
+    case 'gitlab':
+      noun = 'Merge Request';
+      cliName = 'glab';
+      cliArgs = ['mr', 'create'];
+      available = availFn('glab');
+      break;
+    case 'azure':
+      cliName = 'az';
+      cliArgs = ['repos', 'pr', 'create'];
+      available = availFn('az');
+      break;
+    case 'bitbucket':
+      // Bitbucket não possui CLI — nunca chama availFn
+      break;
+    default:
+      // forge desconhecido: sem CLI, sem disponibilidade
+      break;
+  }
+
+  const adapter = { forge, noun, cliName, cliArgs, available };
+
+  adapter.fallbackURL = function (remoteURL, branch) {
+    const base = remoteHTTPSBase(remoteURL, forge);
+    if (!base) return '';
+    switch (forge) {
+      case 'github':    return `${base}/compare/${branch}?expand=1`;
+      case 'gitlab':    return `${base}/-/merge_requests/new?merge_request[source_branch]=${branch}`;
+      case 'bitbucket': return `${base}/pull-requests/new?source=${branch}`;
+      case 'azure':     return `${base}/pullrequestcreate?sourceRef=${branch}`;
+      default:          return '';
+    }
+  };
+
+  return adapter;
+}
+
+module.exports = { forgeAdapter, remoteHTTPSBase };

package/src/forge/resolve.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * forge/resolve.js — Forge resolution for trackfw ship.
+ *
+ * Precedence (highest → lowest):
+ *  1. --forge flag (explicit override)
+ *  2. forge: field in trackfw.yaml
+ *  3. Host extracted from git remote get-url origin
+ *  4. CI configuration files in repo root (.gitlab-ci.yml / .github/workflows/)
+ *  5. "manual" — never an error
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/** Accepted values for the --forge flag and forge: config field. */
+const VALID_FORGES = ['github', 'gitlab', 'bitbucket', 'azure'];
+
+/**
+ * Resolve the forge from the given inputs.
+ *
+ * @param {object} input
+ * @param {string} [input.flagForge]   - value from --forge flag
+ * @param {string} [input.configForge] - value from trackfw.yaml forge: field
+ * @param {string} [input.remoteURL]   - output of "git remote get-url origin"
+ * @param {string} [input.repoDir]     - repo root for CI file detection
+ * @returns {{ forge: string, source: string }} Resolution object.
+ *   forge ∈ {"github", "gitlab", "bitbucket", "azure", "manual"}
+ *   source ∈ {"flag", "config", "remote", "ci", "none"}
+ * @throws {Error} if flagForge or configForge contains an invalid value.
+ */
+function resolve(input) {
+  const { flagForge = '', configForge = '', remoteURL = '', repoDir = '' } = input || {};
+
+  // 1. Explicit flag wins everything.
+  if (flagForge) {
+    validateForge(flagForge);
+    return { forge: flagForge, source: 'flag' };
+  }
+
+  // 2. Config field.
+  if (configForge) {
+    validateForge(configForge);
+    return { forge: configForge, source: 'config' };
+  }
+
+  // 3. Remote URL — known hosts only.
+  if (remoteURL) {
+    const forge = forgeFromRemoteURL(remoteURL);
+    if (forge) return { forge, source: 'remote' };
+  }
+
+  // 4. CI files — desempate for self-hosted / unknown host.
+  if (repoDir) {
+    const forge = forgeFromCI(repoDir);
+    if (forge) return { forge, source: 'ci' };
+  }
+
+  // 5. Manual — not an error.
+  return { forge: 'manual', source: 'none' };
+}
+
+/**
+ * Production entry point: runs "git remote get-url origin" in repoDir,
+ * then calls resolve().
+ */
+function resolveFromRepo(flagForge, configForge, repoDir) {
+  const remoteURL = gitRemoteURL(repoDir);
+  return resolve({ flagForge, configForge, remoteURL, repoDir });
+}
+
+/** @throws {Error} if forge is not in VALID_FORGES */
+function validateForge(forge) {
+  if (!VALID_FORGES.includes(forge)) {
+    throw new Error(
+      `invalid forge "${forge}": accepted values are ${VALID_FORGES.join(', ')}`
+    );
+  }
+}
+
+function forgeFromRemoteURL(rawURL) {
+  const host = extractHost(rawURL);
+  return hostToForge(host);
+}
+
+/**
+ * Extracts the lowercase hostname from HTTPS, SSH (git@) or ssh:// URLs.
+ */
+function extractHost(rawURL) {
+  if (!rawURL) return '';
+  rawURL = rawURL.trim();
+
+  // SSH short form: git@github.com:org/repo.git
+  if (rawURL.startsWith('git@')) {
+    const rest = rawURL.slice(4); // strip "git@"
+    const colonIdx = rest.indexOf(':');
+    if (colonIdx >= 0) return rest.slice(0, colonIdx).toLowerCase();
+    return '';
+  }
+
+  // SSH long form: ssh://git@github.com/org/repo.git
+  if (rawURL.startsWith('ssh://')) {
+    let rest = rawURL.slice(6); // strip "ssh://"
+    const atIdx = rest.indexOf('@');
+    if (atIdx >= 0) rest = rest.slice(atIdx + 1); // strip user@
+    const slashIdx = rest.indexOf('/');
+    return slashIdx >= 0
+      ? rest.slice(0, slashIdx).toLowerCase()
+      : rest.toLowerCase();
+  }
+
+  // HTTPS / HTTP
+  if (rawURL.startsWith('https://') || rawURL.startsWith('http://')) {
+    let rest = rawURL.replace(/^https?:\/\//, '');
+    // strip optional user:pass@
+    const atIdx = rest.indexOf('@');
+    if (atIdx >= 0) rest = rest.slice(atIdx + 1);
+    const slashIdx = rest.indexOf('/');
+    return slashIdx >= 0
+      ? rest.slice(0, slashIdx).toLowerCase()
+      : rest.toLowerCase();
+  }
+
+  return '';
+}
+
+/**
+ * Maps a known hostname to its forge identifier.
+ * Azure DevOps uses dev.azure.com (HTTPS) and ssh.dev.azure.com (SSH).
+ * Returns '' for unknown / self-hosted hosts.
+ */
+function hostToForge(host) {
+  if (!host) return '';
+  if (host === 'github.com') return 'github';
+  if (host === 'gitlab.com') return 'gitlab';
+  if (host === 'bitbucket.org') return 'bitbucket';
+  if (
+    host === 'dev.azure.com' ||
+    host.endsWith('.dev.azure.com') ||
+    host.endsWith('.visualstudio.com')
+  ) {
+    return 'azure';
+  }
+  return '';
+}
+
+/**
+ * Inspects CI indicator files in repoDir.
+ * Priority: .gitlab-ci.yml → gitlab; .github/workflows/ → github.
+ */
+function forgeFromCI(repoDir) {
+  try {
+    fs.statSync(path.join(repoDir, '.gitlab-ci.yml'));
+    return 'gitlab';
+  } catch (_) {}
+
+  try {
+    const stat = fs.statSync(path.join(repoDir, '.github', 'workflows'));
+    if (stat.isDirectory()) return 'github';
+  } catch (_) {}
+
+  return '';
+}
+
+/**
+ * Runs "git remote get-url origin" in repoDir.
+ * Returns '' on any error.
+ */
+function gitRemoteURL(repoDir) {
+  try {
+    return execSync('git remote get-url origin', {
+      cwd: repoDir,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    }).trim();
+  } catch (_) {
+    return '';
+  }
+}
+
+module.exports = {
+  VALID_FORGES,
+  resolve,
+  resolveFromRepo,
+  validateForge,
+  extractHost,
+  hostToForge,
+  forgeFromCI,
+};

package/src/generators/adr.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs')
 const path = require('path')
+const { localDateISO } = require('./date')
 
 /**
  * Converte uma string em slug: lowercase + espaços → hifens.
@@ -9,7 +10,13 @@ const path = require('path')
  * @returns {string}
  */
 function toSlug(s) {
-  return s.toLowerCase().replace(/ /g, '-')
+  // NFKD normalization + remove combining marks (diacríticos) + lowercase + non-alphanumeric → hífen
+  return s
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
 }
 
 /**
@@ -26,11 +33,13 @@ function slugToTitle(slug) {
 }
 
 /**
- * Retorna a data atual no formato YYYY-MM-DD.
+ * Retorna a data LOCAL atual no formato YYYY-MM-DD.
+ * Delega para localDateISO() — usa getDate/getMonth/getFullYear (hora local),
+ * não toISOString (UTC).
  * @returns {string}
  */
 function today() {
-  return new Date().toISOString().slice(0, 10)
+  return localDateISO()
 }
 
 /**
@@ -182,4 +191,4 @@ author: ""
   return filename
 }
 
-module.exports = { newADR, listADRs, newADRDraft, toSlug }
+module.exports = { newADR, listADRs, newADRDraft, toSlug, today }

package/src/generators/date.js

@@ -0,0 +1,23 @@
+'use strict'
+
+/**
+ * localDateISO — retorna a data LOCAL atual no formato YYYY-MM-DD.
+ *
+ * Usa getFullYear/getMonth/getDate (métodos de hora local) em vez de
+ * toISOString() (que retorna sempre UTC). Isso garante que uma REQ criada às
+ * 22h no Brasil seja datada do dia correto, independentemente do fuso da
+ * máquina — comportamento idêntico ao de Go (time.Now().Format("2006-01-02"))
+ * e Python (date.today().isoformat()).
+ *
+ * @returns {string} Data no formato "YYYY-MM-DD"
+ */
+function localDateISO() {
+  const d = new Date()
+  return [
+    d.getFullYear(),
+    String(d.getMonth() + 1).padStart(2, '0'),
+    String(d.getDate()).padStart(2, '0'),
+  ].join('-')
+}
+
+module.exports = { localDateISO }

package/src/generators/init.js

@@ -13,6 +13,7 @@ const GOV_DIRS = [
   'docs/roadmaps/blocked',
   'docs/roadmaps/done',
   'docs/roadmaps/abandoned',
+  'vault/notes',
 ]
 
 const GLOBAL_ADRS_DIRECTIVE = 'Obrigatório: Inspecione e respeite todos os ADRs globais nos diretórios listados em adr_dirs (inclusive caminhos ~/...) antes de propor alterações de arquitetura.'
@@ -28,6 +29,7 @@ async function scaffold(cfg, cwd) {
     console.log(`  ✓ ${dir}`)
   }
 
+  generateVaultIndex(root)
   writeTrackfwConfig(cfg, root)
   generateValidateScript(cfg, root)
   generateAttentionScripts(cfg, root)
@@ -40,6 +42,29 @@ async function scaffold(cfg, cwd) {
   injectHooksDetected(root)
 }
 
+/**
+ * generateVaultIndex — cria vault/notes/index.md se ainda não existir.
+ * @param {string} root
+ */
+function generateVaultIndex(root) {
+  const indexPath = path.join(root || process.cwd(), 'vault', 'notes', 'index.md')
+  if (fs.existsSync(indexPath)) return
+  const content = `# Vault de Conhecimento
+
+> Ponto de entrada de conhecimento do projeto para agentes e pessoas.
+> Cada nota documenta uma causa-raiz, decisão técnica ou restrição não óbvia.
+> Crie notas com: trackfw note new "<título>"
+
+## Índice
+
+<!-- As notas serão listadas abaixo. Exemplo:
+- [nome-da-nota-YYYY-MM-DD](nome-da-nota-YYYY-MM-DD.md)
+-->
+`
+  fs.writeFileSync(indexPath, content, 'utf8')
+  console.log('  ✓ vault/notes/index.md')
+}
+
 // ---------------------------------------------------------------------------
 // trackfw.yaml
 // ---------------------------------------------------------------------------
@@ -54,7 +79,7 @@ backend: ${cfg.backend || ''}
 backend_framework: ${cfg.backendFramework || ''}
 pkg_manager: ${cfg.pkgManager || ''}
 hooks: ${cfg.hooks || ''}
-ci: ${cfg.ci || ''}
+ci: ${cfg.ci || ''}${cfg.forge ? `\nforge: ${cfg.forge}` : ''}
 require_req_in_commit: ${cfg.requireReqInCommit ? 'true' : 'false'}
 
 # governance paths (edit to match your project structure)
@@ -585,6 +610,66 @@ function generateClaudeMD(cfg) {
       content += 'No CI gate configured.\n'
   }
 
+  // Harness sections — derived from project governance conventions
+  content += '\n## Branch strategy\n\n'
+  content += 'One active branch at a time. Name it `feat/<slug>`, `fix/<slug>` or `refactor/<slug>`. '
+  content += 'Before creating a new branch, verify no other is genuinely open: run `git fetch origin --prune`, '
+  content += 'then `git branch -r --no-merged origin/main`, then for each candidate `git diff origin/main <branch> --stat`. '
+  content += 'An empty diff means it was squash-merged — ignore it. '
+  content += 'Squash merges do not mark a branch as merged, so `--no-merged` alone is not evidence. '
+  content += 'If the branch is stale and the diff looks inflated by main\'s own evolution, '
+  content += 'compare only the files the branch itself touched since the merge base.\n\n'
+
+  content += '## Definition of done\n\n'
+  content += 'Green build and tests do not close a microbatch. '
+  content += 'It is done when the requirement and the roadmap sit in the correct state folder, '
+  content += 'their declared status matches that folder, the final validation is recorded with evidence, '
+  content += 'no duplicate copy remains in another state, and `trackfw validate` reports no violations.\n\n'
+
+  content += '## Requirement scope\n\n'
+  content += 'Every requirement must declare an explicit negative scope: what must not be implemented. '
+  content += 'Boundaries prevent an implementing agent from inventing work.\n\n'
+
+  content += '## State requirements\n\n'
+  content += '`blocked` requires a reason and an owner. '
+  content += '`abandoned` requires a reason and a successor. '
+  content += '`wip` must reflect work that is genuinely active; '
+  content += 'anything stalled moves to `blocked` or `abandoned` instead of rotting in `wip`.\n\n'
+
+  content += '## Roadmap format\n\n'
+  content += 'Organize work as waves of microbatches. '
+  content += 'A wave groups microbatches that can run in parallel; a barrier separates waves. '
+  content += 'Microbatches sharing any file — including generated trees and build outputs — must be sequential, '
+  content += 'and the reason is documented. '
+  content += 'Each microbatch declares exact files, exact actions, measurable acceptance criteria and exact validation commands, '
+  content += 'so that a small model can execute it without guessing.\n\n'
+
+  content += '## When governance is not required\n\n'
+  content += 'A closed list of exemptions: a typo or local variable rename; a documentation-only change; '
+  content += 'a configuration tweak with no runtime effect; a direct revert; '
+  content += 'answering a question or reviewing without changes. '
+  content += 'Additionally, when the user reports a concrete bug, fix it directly and do not open an architectural analysis for it. '
+  content += '**This section takes precedence over the general rule that requires a requirement and a roadmap.** '
+  content += 'Anything touching business logic, an API contract, a data schema, authentication or authorization, '
+  content += 'localization, or user-facing behavior always requires governance, regardless of how few files it touches.\n\n'
+
+  content += '## Production incidents\n\n'
+  content += 'Inspect the live environment before proposing a fix: real variables, active credentials, '
+  content += 'granted permissions, running processes. '
+  content += 'Confirm the root cause against real evidence, then implement the smallest fix. '
+  content += 'Never edit static configuration files as a response to a root cause that has not been confirmed in the running environment.\n\n'
+
+  content += '## Iterative prototyping\n\n'
+  content += 'For complex or uncertain user-facing work, validate the concept with a disposable, isolated prototype '
+  content += 'that the user reviews visually, and only then write the decision record and the production roadmap. '
+  content += 'Build and test success is not evidence that an interface is right.\n\n'
+
+  content += '## Autopilot\n\n'
+  content += 'Ask everything you need before starting. '
+  content += 'Once started, do not interrupt for confirmations that could have been anticipated. '
+  content += 'Decide low-risk details autonomously following existing project conventions, '
+  content += 'and record autonomous decisions in the commit message.\n'
+
   injectOrUpdateRules('CLAUDE.md', content)
   console.log('  ✓ CLAUDE.md')
 }
@@ -700,9 +785,16 @@ trackfw não está instalado. Instale com:
    Com base no conteúdo da REQ, gere um roadmap seguindo **estritamente** este formato:
 
    \`\`\`markdown
+   ---
+   status: backlog
+   date: <YYYY-MM-DD>
+   req: "docs/req/<arquivo-selecionado>.md"
+   squad: ""
+   ---
+
    # Roadmap: <título derivado da REQ>
 
-   > Criado em: <YYYY-MM-DD> | Status: ⬜ Backlog
+   > Created: <YYYY-MM-DD> | Status: backlog
 
    ## Diagnóstico / Contexto
    <resumo do problema, motivação e escopo extraídos da REQ>
@@ -720,6 +812,13 @@ trackfw não está instalado. Instale com:
    - [ ] build sem erros
    - [ ] testes verdes
    **Comandos de validação:** \`<comando de build e teste do projeto>\`
+
+   ### ML-1B — <título> (se independente de ML-1A)
+   ...
+
+   ## Wave 2 — <nome> (depende de Wave 1)
+   > Dependências: Wave 1 completa
+   ...
    \`\`\`
 
    **Princípios obrigatórios:**
@@ -732,10 +831,12 @@ trackfw não está instalado. Instale com:
 4. **Salvar o arquivo**
    - Calcule o slug: título em lowercase, espaços → hifens, remova caracteres especiais
    - Crie o arquivo em \`docs/roadmaps/backlog/ROADMAP-<YYYY-MM-DD>-<slug>.md\`
+   - Preencha \`req:\` com o caminho relativo completo da REQ selecionada
    - Use a data de hoje
 
 5. **Confirmar**
-   Informe o caminho do arquivo criado e um resumo das Waves e total de MLs gerados.`,
+   Informe o caminho do arquivo criado e um resumo das Waves e total de MLs gerados.
+`,
 
     'implement.md': `Você é o orquestrador de implementação do trackfw. Siga o fluxo abaixo **sem pular etapas**.
 
@@ -1006,12 +1107,35 @@ async function installAmazonQ(cwd = process.cwd()) {
   }
 }
 
-/** Install the canonical agents and skills for one AI target. */
-async function installIntegrationTarget(target, cwd = process.cwd()) {
-  const { execute } = require('../integrations')
+/**
+ * Install the canonical agents and skills for one AI target.
+ *
+ * `scope` defaults to "project" for backward compatibility with the
+ * compatibility entrypoints below (installAgents, installGemini, etc.), that
+ * historical tests exercise directly without going through the `init`
+ * wizard's scope prompt. `trackfw init` itself always passes the scope it
+ * resolved (ADR-2026-07-25-escopo-de-instalacao-selecionavel-para-agents-e-
+ * skills, D4).
+ */
+async function installIntegrationTarget(target, cwd = process.cwd(), scope = 'project') {
+  const { execute, buildPlans } = require('../integrations')
   const roots = { projectRoot: cwd }
-  execute('agents', 'install', { targets: [target], scope: 'project' }, roots)
-  execute('skills', 'install', { targets: [target], scope: 'project' }, roots)
+  const options = { targets: [target], scope }
+  // D5 — transparency: print resolved destinations before writing anything.
+  // buildPlans has no side effects, so it is safe to call here purely to
+  // enumerate destinations; the actual write happens below via execute().
+  // Mirrors printResolvedDestinations in commands/integrations.js and Go's
+  // installAITools (internal/commands/init.go) — this call site (init's AI
+  // tools install) was the one place that stayed silent (divergence #2,
+  // ROADMAP-2026-07-25-escopo-de-instalacao-selecionavel-para-agents-e-skills).
+  const destinations = [
+    ...buildPlans('agents', options).map(plan => plan.destination),
+    ...buildPlans('skills', options).map(plan => plan.destination),
+  ]
+  console.log(`Destino (${scope}):`)
+  for (const destination of [...new Set(destinations)].sort()) console.log(`  ${destination}`)
+  execute('agents', 'install', options, roots)
+  execute('skills', 'install', options, roots)
   console.log(`  ✓ ${target} agents and skills`)
 }
 
@@ -1116,6 +1240,7 @@ module.exports = {
   generateClaudeMD,
   generateClaudeCommands,
   generateClaudeCommandsForce,
+  generateVaultIndex,
   installSkillsForce,
   installAgents,
   installGemini,