trackfw 2.15.0 → 2.16.0

package/src/i18n/locales/es-ES.json

@@ -15,10 +15,21 @@
       "projectType_fullstack": "Full-stack (frontend + backend)",
       "projectType_frontend": "Solo frontend",
       "projectType_backend": "Solo backend",
-      "projectType_governance": "Solo gobernanza (sin stack de build)"
+      "projectType_governance": "Solo gobernanza (sin stack de build)",
+      "identityPreset": "¿Cómo quieres nombrar a tus agentes?",
+      "identityCustomName": "Nombre de exhibición para el agente",
+      "identityNickname": "¿Cómo debemos llamarte? (opcional)"
     },
     "success": "✓ trackfw inicializado — ejecuta 'trackfw status' para ver el estado de gobernanza."
   },
+  "identity": {
+    "inUse": "identidad: {{count}} agente(s) personalizado(s)",
+    "wizard": {
+      "confirmHeader": "── Confirmación ──────────────────────────────",
+      "confirmQuestion": "¿Confirmar?",
+      "nicknameRowLabel": "Cómo te llamaremos:"
+    }
+  },
   "adr": {
     "description": "Gestionar Architecture Decision Records",
     "new": {

package/src/i18n/locales/pt-BR.json

@@ -15,10 +15,21 @@
       "projectType_fullstack": "Full-stack (frontend + backend)",
       "projectType_frontend": "Somente frontend",
       "projectType_backend": "Somente backend",
-      "projectType_governance": "Somente governança (sem stack de build)"
+      "projectType_governance": "Somente governança (sem stack de build)",
+      "identityPreset": "Como você quer nomear seus agentes?",
+      "identityCustomName": "Nome de exibição para o agente",
+      "identityNickname": "Como devemos te chamar? (opcional)"
     },
     "success": "✓ trackfw inicializado — execute 'trackfw status' para ver o estado de governança."
   },
+  "identity": {
+    "inUse": "identidade: {{count}} agente(s) personalizado(s)",
+    "wizard": {
+      "confirmHeader": "── Confirmação ──────────────────────────────",
+      "confirmQuestion": "Confirmar?",
+      "nicknameRowLabel": "Como você será chamado:"
+    }
+  },
   "adr": {
     "description": "Gerenciar Architecture Decision Records",
     "new": {

package/src/identity/config.js

@@ -0,0 +1,134 @@
+'use strict'
+
+const crypto = require('node:crypto')
+const fs = require('node:fs')
+const path = require('node:path')
+
+// SCHEMA_VERSION é a versão de schema atual do arquivo de configuração de
+// identidade. Espelha internal/identity/identity.go:schemaVersion.
+const SCHEMA_VERSION = 1
+
+// slugPattern casa um slug válido: segmentos alfanuméricos em minúsculas
+// unidos por hífens simples, ex.: "zeus", "meu-agente".
+const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
+function identityPath(homeDir) {
+  return path.join(homeDir, '.trackfw', 'identity.json')
+}
+
+// load lê a configuração de identidade de <homeDir>/.trackfw/identity.json.
+//
+// Se o arquivo não existir, load retorna uma Config vazia sem erro — este é
+// o caminho de não-regressão e nunca deve surgir como falha para quem ainda
+// não customizou sua identidade. Espelha internal/identity/identity.go:Load.
+function load(homeDir) {
+  const filename = identityPath(homeDir)
+  let data
+  try {
+    data = fs.readFileSync(filename, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return { schema_version: SCHEMA_VERSION, agents: {} }
+    throw new Error(`identity: falha ao ler ${filename}: ${err.message}`)
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(data)
+  } catch (err) {
+    throw new Error(`identity: falha ao decodificar ${filename}: ${err.message}`)
+  }
+  if (parsed.schema_version !== SCHEMA_VERSION) {
+    throw new Error(`identity: versao de schema nao suportada em ${filename}: ${parsed.schema_version} (esperado ${SCHEMA_VERSION})`)
+  }
+  if (!parsed.agents || typeof parsed.agents !== 'object') parsed.agents = {}
+  return parsed
+}
+
+// save persiste cfg em <homeDir>/.trackfw/identity.json de forma atômica.
+// Espelha internal/identity/identity.go:Save — inclusive a omissão de
+// user_nickname vazio e agents vazio, que resulta do comportamento
+// omitempty do encoding/json do Go, e a ordenação alfabética das chaves do
+// mapa agents, que resulta da ordenação de mapas do encoding/json do Go.
+function save(homeDir, cfg) {
+  const out = { schema_version: SCHEMA_VERSION }
+  if (cfg.user_nickname) out.user_nickname = cfg.user_nickname
+  const agents = cfg.agents || {}
+  const ids = Object.keys(agents).sort()
+  if (ids.length > 0) {
+    const sortedAgents = {}
+    for (const id of ids) {
+      sortedAgents[id] = { display_name: agents[id].display_name, slug: agents[id].slug }
+    }
+    out.agents = sortedAgents
+  }
+
+  const data = `${JSON.stringify(out, null, 2)}\n`
+  const filename = identityPath(homeDir)
+  atomicWrite(filename, data, 0o600)
+}
+
+// atomicWrite grava data em filename de forma atômica: cria um arquivo
+// temporário no mesmo diretório, escreve, sincroniza e então renomeia para o
+// lugar final. Espelha internal/identity/identity.go:atomicWrite.
+function atomicWrite(filename, data, mode) {
+  const directory = path.dirname(filename)
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
+  const temporaryName = path.join(directory, `.trackfw-tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`)
+  const fd = fs.openSync(temporaryName, 'w', mode)
+  try {
+    fs.writeSync(fd, data)
+    fs.fsyncSync(fd)
+  } finally {
+    fs.closeSync(fd)
+  }
+  fs.renameSync(temporaryName, filename)
+}
+
+// agentName retorna o display name customizado sufixado com "-tf". Este é o
+// único lugar do código onde o sufixo "-tf" é aplicado a um slug. Espelha
+// internal/identity/identity.go:AgentName.
+function agentName(slug) {
+  return `${slug}-tf`
+}
+
+// validate verifica cfg quanto à integridade estrutural e referencial:
+//   - todo id de agente em cfg.agents deve estar presente em knownIds
+//   - display_name não pode ser vazio
+//   - slug deve casar com ^[a-z0-9]+(-[a-z0-9]+)*$
+//   - slugs devem ser únicos entre os agentes
+//   - slug não pode terminar com o sufixo "-tf" (ele é acrescentado
+//     automaticamente por agentName)
+// Espelha internal/identity/identity.go:Validate.
+function validate(cfg, knownIds) {
+  const known = new Set(knownIds)
+  const seenSlugs = new Map()
+  const agents = (cfg && cfg.agents) || {}
+
+  for (const [id, agent] of Object.entries(agents)) {
+    if (!known.has(id)) {
+      throw new Error(`identity: agente desconhecido "${id}" nao esta na lista de agentes conhecidos`)
+    }
+    if (!agent.display_name) {
+      throw new Error(`identity: display_name vazio para o agente "${id}"`)
+    }
+    if (!SLUG_PATTERN.test(agent.slug)) {
+      throw new Error(`identity: slug invalido "${agent.slug}" para o agente "${id}" (esperado padrao ${SLUG_PATTERN.source})`)
+    }
+    if (seenSlugs.has(agent.slug)) {
+      throw new Error(`identity: slug duplicado "${agent.slug}" entre os agentes "${seenSlugs.get(agent.slug)}" e "${id}"`)
+    }
+    if (agent.slug.endsWith('-tf')) {
+      throw new Error(`identity: slug "${agent.slug}" do agente "${id}" nao deve incluir o sufixo "-tf"; ele e acrescentado automaticamente (use "${agent.slug.slice(0, -3)}" em vez de "${agent.slug}")`)
+    }
+    seenSlugs.set(agent.slug, id)
+  }
+}
+
+// lookup retorna a identidade configurada para id, se houver. Espelha
+// internal/identity/identity.go:Lookup.
+function lookup(cfg, id) {
+  const agents = (cfg && cfg.agents) || {}
+  return Object.prototype.hasOwnProperty.call(agents, id) ? agents[id] : undefined
+}
+
+module.exports = { SCHEMA_VERSION, load, save, agentName, validate, lookup, identityPath }

package/src/identity/index.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const { slugify } = require('./slug')
+const { knownAgentIds, preset, presetNames } = require('./preset')
+const { load, save, agentName, validate, lookup, identityPath, SCHEMA_VERSION } = require('./config')
+
+module.exports = {
+  slugify,
+  knownAgentIds,
+  preset,
+  presetNames,
+  load,
+  save,
+  agentName,
+  validate,
+  lookup,
+  identityPath,
+  SCHEMA_VERSION,
+}

package/src/identity/preset.js

@@ -0,0 +1,197 @@
+'use strict'
+
+// knownAgentIds retorna a lista canônica de ids de agentes conhecidos pelo
+// trackfw, em ordem estável e determinística. Espelha
+// internal/identity/preset.go:KnownAgentIDs.
+function knownAgentIds() {
+  return [
+    'architect',
+    'backend',
+    'frontend',
+    'qa',
+    'infra',
+    'security',
+    'dba',
+    'ux',
+    'code-quality',
+    'data',
+  ]
+}
+
+// presets contém o catálogo de presets temáticos de identidade. display_name
+// e slug são HARDCODED aqui — não derivados chamando slugify em tempo de
+// execução — porque essa é uma decisão explícita do ADR: hardcoding evita
+// depender do comportamento de normalização Unicode sendo idêntico entre os
+// CLIs Go, Node.js e Python. Espelha internal/identity/preset.go:presets.
+const PRESETS = {
+  greek: {
+    architect: { display_name: 'Zeus', slug: 'zeus' },
+    backend: { display_name: 'Apolo', slug: 'apolo' },
+    frontend: { display_name: 'Afrodite', slug: 'afrodite' },
+    qa: { display_name: 'Ártemis', slug: 'artemis' },
+    infra: { display_name: 'Ares', slug: 'ares' },
+    security: { display_name: 'Hades', slug: 'hades' },
+    dba: { display_name: 'Poseidon', slug: 'poseidon' },
+    ux: { display_name: 'Atena', slug: 'atena' },
+    'code-quality': { display_name: 'Hefesto', slug: 'hefesto' },
+    data: { display_name: 'Métis', slug: 'metis' },
+  },
+  norse: {
+    architect: { display_name: 'Odin', slug: 'odin' },
+    backend: { display_name: 'Thor', slug: 'thor' },
+    frontend: { display_name: 'Freya', slug: 'freya' },
+    qa: { display_name: 'Heimdall', slug: 'heimdall' },
+    infra: { display_name: 'Tyr', slug: 'tyr' },
+    security: { display_name: 'Vidar', slug: 'vidar' },
+    dba: { display_name: 'Njord', slug: 'njord' },
+    ux: { display_name: 'Idun', slug: 'idun' },
+    'code-quality': { display_name: 'Bragi', slug: 'bragi' },
+    data: { display_name: 'Mimir', slug: 'mimir' },
+  },
+  potter: {
+    architect: { display_name: 'Dumbledore', slug: 'dumbledore' },
+    backend: { display_name: 'Snape', slug: 'snape' },
+    frontend: { display_name: 'Luna', slug: 'luna' },
+    qa: { display_name: 'Moody', slug: 'moody' },
+    infra: { display_name: 'Hagrid', slug: 'hagrid' },
+    security: { display_name: 'Kingsley', slug: 'kingsley' },
+    dba: { display_name: 'Flitwick', slug: 'flitwick' },
+    ux: { display_name: 'Tonks', slug: 'tonks' },
+    'code-quality': { display_name: 'Hermione', slug: 'hermione' },
+    data: { display_name: 'Trelawney', slug: 'trelawney' },
+  },
+  thrones: {
+    architect: { display_name: 'Tyrion', slug: 'tyrion' },
+    backend: { display_name: 'Jon', slug: 'jon' },
+    frontend: { display_name: 'Sansa', slug: 'sansa' },
+    qa: { display_name: 'Arya', slug: 'arya' },
+    infra: { display_name: 'Brienne', slug: 'brienne' },
+    security: { display_name: 'Varys', slug: 'varys' },
+    dba: { display_name: 'Samwell', slug: 'samwell' },
+    ux: { display_name: 'Margaery', slug: 'margaery' },
+    'code-quality': { display_name: 'Stannis', slug: 'stannis' },
+    data: { display_name: 'Bran', slug: 'bran' },
+  },
+  chaves: {
+    architect: { display_name: 'Girafales', slug: 'girafales' },
+    backend: { display_name: 'Madruga', slug: 'madruga' },
+    frontend: { display_name: 'Chiquinha', slug: 'chiquinha' },
+    qa: { display_name: 'Florinda', slug: 'florinda' },
+    infra: { display_name: 'Barriga', slug: 'barriga' },
+    security: { display_name: 'Quico', slug: 'quico' },
+    dba: { display_name: 'Clotilde', slug: 'clotilde' },
+    ux: { display_name: 'Popis', slug: 'popis' },
+    'code-quality': { display_name: 'Nhonho', slug: 'nhonho' },
+    data: { display_name: 'Godinez', slug: 'godinez' },
+  },
+  pioneers: {
+    architect: { display_name: 'Turing', slug: 'turing' },
+    backend: { display_name: 'Ritchie', slug: 'ritchie' },
+    frontend: { display_name: 'Berners-Lee', slug: 'berners-lee' },
+    qa: { display_name: 'Hamilton', slug: 'hamilton' },
+    infra: { display_name: 'Torvalds', slug: 'torvalds' },
+    security: { display_name: 'Diffie', slug: 'diffie' },
+    dba: { display_name: 'Codd', slug: 'codd' },
+    ux: { display_name: 'Norman', slug: 'norman' },
+    'code-quality': { display_name: 'Knuth', slug: 'knuth' },
+    data: { display_name: 'Hopper', slug: 'hopper' },
+  },
+  starwars: {
+    architect: { display_name: 'Yoda', slug: 'yoda' },
+    backend: { display_name: 'Han', slug: 'han' },
+    frontend: { display_name: 'Leia', slug: 'leia' },
+    qa: { display_name: 'Ahsoka', slug: 'ahsoka' },
+    infra: { display_name: 'Chewbacca', slug: 'chewbacca' },
+    security: { display_name: 'Vader', slug: 'vader' },
+    dba: { display_name: 'R2-D2', slug: 'r2-d2' },
+    ux: { display_name: 'Padmé', slug: 'padme' },
+    'code-quality': { display_name: 'Obi-Wan', slug: 'obi-wan' },
+    data: { display_name: 'C-3PO', slug: 'c-3po' },
+  },
+  tolkien: {
+    architect: { display_name: 'Gandalf', slug: 'gandalf' },
+    backend: { display_name: 'Aragorn', slug: 'aragorn' },
+    frontend: { display_name: 'Arwen', slug: 'arwen' },
+    qa: { display_name: 'Legolas', slug: 'legolas' },
+    infra: { display_name: 'Gimli', slug: 'gimli' },
+    security: { display_name: 'Boromir', slug: 'boromir' },
+    dba: { display_name: 'Elrond', slug: 'elrond' },
+    ux: { display_name: 'Galadriel', slug: 'galadriel' },
+    'code-quality': { display_name: 'Faramir', slug: 'faramir' },
+    data: { display_name: 'Bilbo', slug: 'bilbo' },
+  },
+  turma: {
+    architect: { display_name: 'Franjinha', slug: 'franjinha' },
+    backend: { display_name: 'Cebolinha', slug: 'cebolinha' },
+    frontend: { display_name: 'Magali', slug: 'magali' },
+    qa: { display_name: 'Mônica', slug: 'monica' },
+    infra: { display_name: 'Cascão', slug: 'cascao' },
+    security: { display_name: 'Bidu', slug: 'bidu' },
+    dba: { display_name: 'Marocas', slug: 'marocas' },
+    ux: { display_name: 'Anjinho', slug: 'anjinho' },
+    'code-quality': { display_name: 'Titi', slug: 'titi' },
+    data: { display_name: 'Chico', slug: 'chico' },
+  },
+  egyptian: {
+    architect: { display_name: 'Thoth', slug: 'thoth' },
+    backend: { display_name: 'Rá', slug: 'ra' },
+    frontend: { display_name: 'Ísis', slug: 'isis' },
+    qa: { display_name: 'Hórus', slug: 'horus' },
+    infra: { display_name: 'Ptah', slug: 'ptah' },
+    security: { display_name: 'Anúbis', slug: 'anubis' },
+    dba: { display_name: 'Seshat', slug: 'seshat' },
+    ux: { display_name: 'Bastet', slug: 'bastet' },
+    'code-quality': { display_name: 'Maat', slug: 'maat' },
+    data: { display_name: 'Osíris', slug: 'osiris' },
+  },
+}
+
+// presetOrder é a ordem canônica e estável em que os nomes de presets são
+// listados (ex.: por presetNames e em mensagens de erro).
+const PRESET_ORDER = ['greek', 'norse', 'potter', 'thrones', 'chaves', 'pioneers', 'starwars', 'tolkien', 'turma', 'egyptian']
+
+// preset retorna a Config de identidade para o nome de preset temático dado.
+// Se name não for um preset conhecido, lança erro listando os nomes válidos.
+//
+// A Config retornada é sempre uma cópia: mutá-la não afeta a tabela de
+// presets no nível do módulo nem qualquer outra Config retornada por uma
+// chamada anterior a preset().
+function preset(name) {
+  const agents = PRESETS[name]
+  if (!agents) {
+    throw new Error(`identity: preset desconhecido "${name}" (validos: ${presetNames().join(', ')})`)
+  }
+  const copied = {}
+  for (const [id, agent] of Object.entries(agents)) {
+    copied[id] = { display_name: agent.display_name, slug: agent.slug }
+  }
+  return { schema_version: 1, agents: copied }
+}
+
+// presetNames retorna os nomes de todos os presets conhecidos, na ordem
+// estável: greek, norse, potter, thrones, chaves, pioneers, starwars,
+// tolkien, turma, egyptian.
+function presetNames() {
+  return [...PRESET_ORDER]
+}
+
+// Verificação em tempo de carga do módulo: presetOrder e PRESETS devem estar
+// em sincronia — guarda defensiva contra drift silencioso entre o mapa e a
+// ordem documentada (espelha o init() de internal/identity/preset.go).
+;(function assertPresetOrderInSync() {
+  if (PRESET_ORDER.length !== Object.keys(PRESETS).length) {
+    throw new Error('identity: presetOrder e PRESETS fora de sincronia')
+  }
+  const seen = new Set()
+  for (const name of PRESET_ORDER) {
+    if (!PRESETS[name]) {
+      throw new Error(`identity: preset "${name}" listado em presetOrder mas ausente de PRESETS`)
+    }
+    seen.add(name)
+  }
+  if (seen.size !== PRESET_ORDER.length) {
+    throw new Error('identity: presetOrder contem nomes duplicados')
+  }
+})()
+
+module.exports = { knownAgentIds, preset, presetNames }

package/src/identity/slug.js

@@ -0,0 +1,62 @@
+'use strict'
+
+// maxSlugLength é o tamanho máximo aceito para um slug gerado.
+const MAX_SLUG_LENGTH = 40
+
+// collapseDashes colapsa sequências de '-' em um único '-'.
+function collapseDashes(value) {
+  let out = ''
+  let previousDash = false
+  for (const char of value) {
+    if (char === '-') {
+      if (previousDash) continue
+      previousDash = true
+    } else {
+      previousDash = false
+    }
+    out += char
+  }
+  return out
+}
+
+// slugify converte input em um slug normalizado que casa com
+// ^[a-z0-9]+(-[a-z0-9]+)*$.
+//
+// Passos, na ordem exata (espelham internal/identity/slug.go):
+//   1. Normalização Unicode NFD + remoção de marcas diacríticas (\p{Mn}).
+//   2. Lowercase.
+//   3. Espaços (incluindo sequências) e underscores viram '-'.
+//   4. Qualquer caractere fora de [a-z0-9-] é descartado.
+//   5. Sequências de '-' colapsam em um único '-'.
+//   6. '-' nas bordas (início/fim) são removidos.
+//   7. Resultado vazio é erro.
+//   8. Resultado com mais de 40 caracteres é erro.
+//
+// slugify nunca "corrige" silenciosamente uma entrada degenerada — sempre
+// lança erro em vez de adivinhar.
+function slugify(input) {
+  const folded = String(input).normalize('NFD').replace(/\p{Mn}/gu, '')
+  const lowered = folded.toLowerCase()
+  const replaced = lowered.replace(/[ _]/g, '-')
+
+  let filtered = ''
+  for (const char of replaced) {
+    if ((char >= 'a' && char <= 'z') || (char >= '0' && char <= '9') || char === '-') {
+      filtered += char
+    }
+  }
+
+  const collapsed = collapseDashes(filtered)
+  const trimmed = collapsed.replace(/^-+/, '').replace(/-+$/, '')
+
+  if (trimmed === '') {
+    throw new Error(`identity: slug vazio para "${input}"`)
+  }
+  if (trimmed.length > MAX_SLUG_LENGTH) {
+    throw new Error(`identity: slug "${trimmed}" excede o tamanho maximo de ${MAX_SLUG_LENGTH} caracteres (tem ${trimmed.length})`)
+  }
+
+  return trimmed
+}
+
+module.exports = { slugify, MAX_SLUG_LENGTH }

package/src/integrations/index.js

@@ -1,9 +1,12 @@
 'use strict'
 
+const os = require('node:os')
+
 const { catalog, items, target, surfaceFor, readAsset } = require('./catalog')
 const { render } = require('./render')
 const { IntegrationManager } = require('./manager')
 const { legacyHashes } = require('./legacy')
+const identityStore = require('../identity')
 
 function parseSurfaces(values = []) {
   const result = {}
@@ -40,6 +43,7 @@ function selections(kind, options = {}) {
 
 function buildPlans(kind, options = {}) {
   const selected = selections(kind, options)
+  const identityConfig = options.identity || { agents: {} }
   const plans = []
   for (const { target: targetEntry, surface } of selected.targets) {
     const capability = surface.capabilities[kind]
@@ -50,7 +54,7 @@ function buildPlans(kind, options = {}) {
       for (const item of selected.itemEntries) {
         for (const installPath of paths) {
           const destination = installPath.path.replace('{{id}}', item.id)
-          const content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination })
+          const content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination, identity: identityConfig })
           const claim = { target: targetEntry.id, surface: surface.id, scope, kind, item: item.id }
           plans.push({
             claim,
@@ -89,7 +93,13 @@ function result(kind, plans, statuses) {
 }
 
 function execute(kind, operation, options = {}, roots = {}) {
-  const plans = buildPlans(kind, options)
+  // A identidade é resolvida do disco antes de buildPlans — pular esta etapa
+  // reverteria silenciosamente os nomes customizados dos agentes para os
+  // defaults neutros (espelha internal/commands/integrations_flags.go:
+  // executeIntegrationMutation/executeIntegrationList).
+  const homeRoot = roots.homeRoot || os.homedir()
+  const identityConfig = options.identity !== undefined ? options.identity : identityStore.load(homeRoot)
+  const plans = buildPlans(kind, { ...options, identity: identityConfig })
   const manager = new IntegrationManager(roots)
   let statuses
   if (operation === 'list') statuses = manager.inspect(plans)

package/src/integrations/manager.js

@@ -5,6 +5,8 @@ const fs = require('node:fs')
 const os = require('node:os')
 const path = require('node:path')
 
+const { frontmatterName } = require('./render')
+
 const SCHEMA_VERSION = 1
 const sha256 = content => crypto.createHash('sha256').update(content).digest('hex')
 const claimKey = claim => [claim.target, claim.surface, claim.scope, claim.kind, claim.item].join('\u0000')
@@ -28,7 +30,7 @@ class IntegrationManager {
     } else if (path.isAbsolute(destination)) {
       resolved = path.normalize(destination)
     } else {
-      if (!destination || path.normalize(destination) !== destination || destination === '.' || destination.startsWith(`..${path.sep}`)) throw new Error(`Unsafe destination: ${destination}`)
+      if (!destination || path.posix.normalize(destination) !== destination || destination === '.' || destination.startsWith('../')) throw new Error(`Unsafe destination: ${destination}`)
       resolved = path.resolve(root, destination)
     }
     const rel = path.relative(root, resolved)
@@ -145,6 +147,7 @@ class IntegrationManager {
   }
 
   preflight(operation, { plan, file }, manifest, force) {
+    if (operation !== 'uninstall') this.detectNameCollision(plan, file, force)
     const status = this.inspectResolved(plan, file, manifest)
     const record = manifest.artifacts[file]
     const owned = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))
@@ -159,6 +162,53 @@ class IntegrationManager {
     }
   }
 
+  // detectNameCollision protege contra dois artefatos de agente gerenciados
+  // distintos declarando o mesmo "name" de frontmatter dentro do mesmo
+  // diretório de destino (ADR ADR-2026-07-25-identidade-personalizavel-de-
+  // agentes, seção D4). Isso importa porque, com identidades customizáveis,
+  // dois item.id diferentes poderiam resolver para o mesmo nome renderizado
+  // (ex.: dois agentes ambos apontados para o slug "zeus"), e algumas
+  // surfaces usam esse campo name para descoberta de agentes.
+  //
+  // Limitação: a varredura só inspeciona irmãos ".md", porque é o único
+  // formato onde temos uma forma barata e sem dependências (frontmatterName)
+  // de ler de volta o name declarado a partir de bytes já renderizados.
+  // Artefatos JSON (cli-agent-json/agent-json) e TOML (custom-agent-toml)
+  // não são varridos para colisões. Espelha
+  // internal/integrations/manager.go:detectNameCollision.
+  detectNameCollision(plan, file, force) {
+    if (plan.claim.kind !== 'agents') return
+    if (path.extname(file) !== '.md') return
+    const desiredName = frontmatterName(plan.content)
+    if (!desiredName) return
+    const directory = path.dirname(file)
+    let entries
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true })
+    } catch (err) {
+      if (err.code === 'ENOENT') return
+      throw new Error(`scan ${directory} for name collisions: ${err.message}`)
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() || path.extname(entry.name) !== '.md') continue
+      const candidate = path.join(directory, entry.name)
+      if (candidate === file) continue
+      let data
+      try {
+        data = fs.readFileSync(candidate)
+      } catch {
+        continue
+      }
+      const candidateName = frontmatterName(data)
+      if (!candidateName || candidateName !== desiredName) continue
+      if (force) {
+        process.stderr.write(`aviso: ${candidate} declara o mesmo name ${desiredName} que ${file}; prosseguindo por --force\n`)
+        continue
+      }
+      throw new Error(`artifact ${file} declares name ${desiredName} which collides with existing file ${candidate}`)
+    }
+  }
+
   inspectResolved(plan, file, manifest) {
     const record = manifest.artifacts[file]
     const managed = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))