trackfw 6.10.0 → 7.1.0

package/src/generators/init.js

@@ -3,6 +3,7 @@
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
+const { readAgentConventions } = require('../config/index.js')
 
 const GOV_DIRS = [
   'docs/adr',
@@ -34,6 +35,7 @@ async function scaffold(cfg, cwd) {
   generateValidateScript(cfg, root)
   generateAttentionScripts(cfg, root)
   generateCredentialGuardScript(root)
+  generateGitBranchGuardScript(root)
   generateCIWorkflow(cfg, root)
   generateGitHooks(cfg, root)
   generateCommitMsgHook(cfg, root)
@@ -174,6 +176,11 @@ function generateCredentialGuardScript(cwd) {
   gen(cwd || process.cwd())
 }
 
+function generateGitBranchGuardScript(cwd) {
+  const { generateGitBranchGuardScript: gen } = require('./hooks')
+  gen(cwd || process.cwd())
+}
+
 function injectHooksDetected(cwd) {
   const { injectHooksDetected: inject } = require('./hooks')
   inject(cwd || process.cwd())
@@ -392,7 +399,20 @@ const AGENT_HEADERS = {
   cursor:   '---\ndescription: trackfw governance rules\nglob: "**/*"\nalwaysApply: true\n---\n',
 }
 
-function trackfwRulesBlock() {
+function trackfwRulesBlock(agentConventions) {
+  let conventionsSection = ''
+  if (agentConventions && String(agentConventions).trim() !== '') {
+    conventionsSection = `
+
+### Project Conventions
+> Declared by the team in \`trackfw.yaml\`'s \`agent_conventions\` field — NOT
+> inferred automatically. trackfw does not impose an architectural standard; it only
+> propagates what the project has already decided.
+
+${String(agentConventions).trim()}
+`
+  }
+
   return RULES_START + `
 ## trackfw — Governance Rules
 
@@ -435,7 +455,7 @@ Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
 - **Security wave:** include a red-team review wave in every feature roadmap
 - **Test coverage:** TDD for critical logic; min 60% (prototype) / 80% (production)
 - Use \`/trackfw:architect\` to define stack before the first REQ
-
+` + conventionsSection + `
 ### Key Commands
 - \`trackfw context\` — current governance state (always run first)
 - \`trackfw status\` — all artifacts and states
@@ -451,10 +471,10 @@ Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
  * - Arquivo existe, sem marcador: appenda o bloco no final
  * - Arquivo existe, com marcador: substitui conteúdo entre marcadores
  */
-function injectOrUpdateRules(filePath, headerIfNew) {
+function injectOrUpdateRules(filePath, headerIfNew, cwd) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true })
 
-  const block = trackfwRulesBlock()
+  const block = trackfwRulesBlock(readAgentConventions(cwd))
 
   if (!fs.existsSync(filePath)) {
     let content = headerIfNew || ''
@@ -497,7 +517,8 @@ function injectRulesForTool(tool, cwd) {
   const relPath = AGENT_FILES[tool]
   if (!relPath) return
   const header = AGENT_HEADERS[tool] || ''
-  injectOrUpdateRules(path.join(cwd || process.cwd(), relPath), header)
+  const root = cwd || process.cwd()
+  injectOrUpdateRules(path.join(root, relPath), header, root)
 }
 
 /**
@@ -702,7 +723,7 @@ function generateClaudeMD(cfg) {
   content += 'Decide low-risk details autonomously following existing project conventions, '
   content += 'and record autonomous decisions in the commit message.\n'
 
-  injectOrUpdateRules('CLAUDE.md', content)
+  injectOrUpdateRules('CLAUDE.md', content, '.')
   console.log('  ✓ CLAUDE.md')
 }
 
@@ -1329,6 +1350,7 @@ module.exports = {
   generateValidateScript,
   generateAttentionScripts,
   generateCredentialGuardScript,
+  generateGitBranchGuardScript,
   generateCIWorkflow,
   generateGitHooks,
   generateCommitMsgHook,

package/src/i18n/locales/en-US.json

@@ -115,31 +115,10 @@
     "tail": "Number of recent transitions to show",
     "header": "── trackfw log ─────────────────────────"
   },
-  "plugins": {
-    "description": "Manage trackfw plugins",
-    "list": {
-      "description": "List installed plugins",
-      "empty": "No plugins installed. Use `trackfw plugins add <user/repo>` to install one."
-    },
-    "add": {
-      "description": "Install a plugin from GitHub Releases (user/repo or user/repo@tag)",
-      "installing": "Installing plugin from {{repo}}...",
-      "success": "Plugin \"{{name}}\" installed successfully."
-    },
-    "remove": {
-      "description": "Remove an installed plugin",
-      "success": "Plugin \"{{name}}\" removed."
-    }
-  },
   "metrics": {
     "description": "Show delivery metrics",
     "no_data": "No transitions recorded yet.",
     "since": "Filter by period (e.g. 7d, 30d, 90d)",
     "export": "Export metrics to CSV file"
-  },
-  "errors": {
-    "notFound": "Not found: {{path}}",
-    "downloadFailed": "download failed: HTTP {{status}} for {{url}}",
-    "pluginNotFound": "plugin \"{{name}}\" not found"
   }
 }

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

@@ -115,31 +115,10 @@
     "tail": "Número de transiciones recientes a mostrar",
     "header": "── trackfw log ─────────────────────────"
   },
-  "plugins": {
-    "description": "Gestionar plugins de trackfw",
-    "list": {
-      "description": "Listar plugins instalados",
-      "empty": "No hay plugins instalados. Usa `trackfw plugins add <user/repo>` para instalar uno."
-    },
-    "add": {
-      "description": "Instalar un plugin desde GitHub Releases (user/repo o user/repo@tag)",
-      "installing": "Instalando plugin desde {{repo}}...",
-      "success": "Plugin \"{{name}}\" instalado correctamente."
-    },
-    "remove": {
-      "description": "Eliminar un plugin instalado",
-      "success": "Plugin \"{{name}}\" eliminado."
-    }
-  },
   "metrics": {
     "description": "Muestra métricas de entrega",
     "no_data": "No hay transiciones registradas aún.",
     "since": "Filtrar por período (ej: 7d, 30d, 90d)",
     "export": "Exportar métricas a archivo CSV"
-  },
-  "errors": {
-    "notFound": "No encontrado: {{path}}",
-    "downloadFailed": "fallo en la descarga: HTTP {{status}} para {{url}}",
-    "pluginNotFound": "plugin \"{{name}}\" no encontrado"
   }
 }

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

@@ -115,31 +115,10 @@
     "tail": "Número de transições recentes a exibir",
     "header": "── trackfw log ─────────────────────────"
   },
-  "plugins": {
-    "description": "Gerenciar plugins do trackfw",
-    "list": {
-      "description": "Listar plugins instalados",
-      "empty": "Nenhum plugin instalado. Use `trackfw plugins add <user/repo>` para instalar um."
-    },
-    "add": {
-      "description": "Instalar um plugin do GitHub Releases (user/repo ou user/repo@tag)",
-      "installing": "Instalando plugin de {{repo}}...",
-      "success": "Plugin \"{{name}}\" instalado com sucesso."
-    },
-    "remove": {
-      "description": "Remover um plugin instalado",
-      "success": "Plugin \"{{name}}\" removido."
-    }
-  },
   "metrics": {
     "description": "Exibe métricas de delivery",
     "no_data": "Nenhuma transição registrada ainda.",
     "since": "Filtrar por período (ex: 7d, 30d, 90d)",
     "export": "Exportar métricas para arquivo CSV"
-  },
-  "errors": {
-    "notFound": "Não encontrado: {{path}}",
-    "downloadFailed": "falha no download: HTTP {{status}} para {{url}}",
-    "pluginNotFound": "plugin \"{{name}}\" não encontrado"
   }
 }

package/src/integrations/index.js

@@ -8,6 +8,7 @@ const { IntegrationManager } = require('./manager')
 const { legacyHashes } = require('./legacy')
 const identityStore = require('../identity')
 const { injectRulesForTool } = require('../generators/init')
+const { applyThirdPartyReferences } = require('../thirdparty/references')
 
 function parseSurfaces(values = []) {
   const result = {}
@@ -55,7 +56,17 @@ 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, identity: identityConfig })
+          let content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination, identity: identityConfig })
+          // D5/D9 extension point: reproduce any persisted third-party
+          // reference block so regenerating this exact artifact (e.g. a
+          // later `trackfw agents update`) settles at state "current"
+          // instead of treating the attachment as drift. See the doc
+          // comment on applyThirdPartyReferences (../thirdparty/references.js)
+          // for why this cannot live inside render() itself. Mirrors
+          // internal/integrations/plan.go:BuildPlans.
+          if (kind === 'agents' && options.projectRoot) {
+            content = applyThirdPartyReferences(options.projectRoot, content, targetEntry.id, item.id)
+          }
           const claim = { target: targetEntry.id, surface: surface.id, scope, kind, item: item.id }
           plans.push({
             claim,
@@ -100,8 +111,14 @@ function execute(kind, operation, options = {}, roots = {}) {
   // 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, { onSkip: options.onSkip })
+  // D5/D9: manager.roots.project lets buildPlans reproduce any persisted
+  // third-party reference block (see the projectRoot doc comment above the
+  // applyThirdPartyReferences call in buildPlans) so a plain `agents update`
+  // settles at state "current" after a third-party attachment instead of
+  // reporting drift. Mirrors internal/commands/integrations_flags.go passing
+  // manager.ProjectRoot to BuildPlans at both call sites.
+  const plans = buildPlans(kind, { ...options, identity: identityConfig, projectRoot: options.projectRoot || manager.roots.project })
   let statuses
   if (operation === 'list') statuses = manager.inspect(plans)
   else if (operation === 'install') statuses = manager.install(plans, { force: options.force })

package/src/integrations/manager.js

@@ -10,13 +10,34 @@ const { tildeify } = require('../lib/update-engine')
 
 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')
-const cleanClaim = claim => ({ target: claim.target, surface: claim.surface, scope: claim.scope, kind: claim.kind, item: claim.item })
+// claimKey includes origin (ADR-2026-08-15 D11) so a catalog claim and a
+// third-party claim that happen to share target/surface/scope/kind/item are
+// never treated as the same ownership record — mirrors Go's Claim struct
+// equality (`==`), field-by-field, which already includes Origin
+// (internal/integrations/manager.go's claimOwned/appendClaim/removeClaim).
+const claimKey = claim => [claim.target, claim.surface, claim.scope, claim.kind, claim.item, claim.origin || ''].join('\u0000')
+// cleanClaim omits origin entirely when falsy/absent, mirroring Go's
+// `json:"origin,omitempty"` — a catalog claim (origin "") must serialize
+// with NO "origin" key at all, byte-identical to a manifest written before
+// this field existed (retrocompatibility, D11).
+const cleanClaim = claim => {
+  const out = { target: claim.target, surface: claim.surface, scope: claim.scope, kind: claim.kind, item: claim.item }
+  if (claim.origin) out.origin = claim.origin
+  return out
+}
 
 class IntegrationManager {
   constructor({ projectRoot = process.cwd(), homeRoot = os.homedir() } = {}, { onSkip } = {}) {
     this.roots = { project: path.resolve(projectRoot), global: path.resolve(homeRoot) }
     this.onSkip = onSkip
+    // _afterManifestPersist, when set, runs immediately after manifests are
+    // persisted and before artifact bytes are written during install/update
+    // (never during uninstall, which is intentionally not inverted — see the
+    // comment in mutate()). It exists only so tests can simulate an
+    // interruption exactly at the ADR-2026-08-18 ordering seam. Production
+    // code never assigns it. Mirrors internal/integrations/manager.go's
+    // afterManifestPersist package var.
+    this._afterManifestPersist = undefined
   }
 
   manifestPath(scope) { return path.join(this.roots[scope], '.trackfw', 'integrations-manifest.json') }
@@ -105,7 +126,16 @@ class IntegrationManager {
       const file = this.resolve(scope, plan.destination)
       const record = manifests.get(scope).artifacts[file]
       const managed = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))
-      if (!fs.existsSync(file)) return { ...plan, destination: file, state: 'not-installed', managed }
+      // registered reports whether the manifest has ANY entry for this
+      // destination, regardless of claim ownership — unlike managed, which
+      // additionally requires this exact claim to own that entry. doctor
+      // (ML-2A) needs this distinction: a destination registered under a
+      // *different* claim must never be reported as an "unregistered
+      // write" — that would be the dominant false-positive doctor exists to
+      // avoid. Additive field; mirrors Inspection.Registered
+      // (internal/integrations/manager.go).
+      const registered = Boolean(record)
+      if (!fs.existsSync(file)) return { ...plan, destination: file, state: 'not-installed', managed, registered }
       const actual = sha256(fs.readFileSync(file))
       const desired = sha256(plan.content)
       let state
@@ -116,7 +146,7 @@ class IntegrationManager {
       } else if (actual === desired) state = 'current'
       else if ((plan.legacyHashes || []).includes(actual)) state = 'outdated'
       else state = 'modified'
-      return { ...plan, destination: file, state, managed }
+      return { ...plan, destination: file, state, managed, registered }
     })
   }
 
@@ -154,9 +184,44 @@ class IntegrationManager {
     const snapshots = new Map()
     for (const item of active) this.snapshot(snapshots, item.file)
     for (const scope of manifests.keys()) this.snapshot(snapshots, this.manifestPath(scope))
-    try {
-      for (const item of active) this.apply(operation, item, manifests.get(item.plan.claim.scope), force)
+    const saveManifests = () => {
       for (const [scope, manifest] of [...manifests].sort(([a], [b]) => a.localeCompare(b))) this.saveManifest(scope, manifest)
+    }
+    try {
+      // ADR-2026-08-18: install/update persist the manifest before writing
+      // artifact bytes (self-healing direction on interruption); uninstall
+      // keeps the original artifacts-before-manifest order. The two are
+      // deliberately NOT symmetric.
+      if (operation === 'uninstall') {
+        // Uninstall is not inverted. Removing bytes first and persisting the
+        // manifest last means an interruption leaves the manifest still
+        // declaring an artifact whose file is now absent — inspectResolved
+        // resolves that as 'not-installed', the same self-healing direction
+        // install/update get from the inversion below. Inverting uninstall
+        // the same way (drop the manifest entry, then remove bytes) would
+        // instead leave, on interruption, a file on disk whose content still
+        // matches the catalog template but with no manifest entry at all —
+        // reported as an orphaned state='current'/managed=false artifact
+        // that looks legitimate and that nothing detects or repairs
+        // automatically. That is exactly the "disk ahead of manifest" bad
+        // direction the ADR exists to eliminate, so uninstall must not be
+        // simetrized with install/update here. Mirrors the comment in
+        // internal/integrations/manager.go:mutate.
+        for (const item of active) this.applyUninstall(item, manifests.get(item.plan.claim.scope))
+        saveManifests()
+      } else {
+        // Install/Update: compute the manifest update for every active item
+        // in memory (no bytes touched yet), persist all manifests, and only
+        // then write the artifact bytes.
+        const pendingWrites = []
+        for (const item of active) {
+          const write = this.planArtifactWrite(operation, item, manifests.get(item.plan.claim.scope), force)
+          if (write) pendingWrites.push(write)
+        }
+        saveManifests()
+        if (typeof this._afterManifestPersist === 'function') this._afterManifestPersist()
+        for (const write of pendingWrites) this.atomicWrite(write.file, write.content, write.mode)
+      }
     } catch (error) {
       this.rollback(snapshots)
       throw error
@@ -173,7 +238,7 @@ class IntegrationManager {
       if (status.state === 'modified' && !force) throw new Error(`Artifact is modified; use --force: ${file}`)
       if (status.state === 'outdated' && owned && !force) return true // skip: bytes preserved, batch continues
     } else if (operation === 'update') {
-      if (!owned && status.state === 'modified') throw new Error(`Unmanaged artifact does not match a trackfw template: ${file}`)
+      if (!owned && status.state === 'modified') throw new Error(this.unmanagedArtifactError(file, plan.claim))
       if (status.state === 'modified' && !force) throw new Error(`Artifact is modified; use --force: ${file}`)
     } else if (operation === 'uninstall' && owned && status.state === 'modified' && !force) {
       throw new Error(`Artifact is modified; use --force: ${file}`)
@@ -243,19 +308,42 @@ class IntegrationManager {
     return { state: 'modified', managed: false }
   }
 
-  apply(operation, { plan, file }, manifest, force) {
+  // applyUninstall removes ownership of one artifact from the manifest, and —
+  // once no claim remains — the artifact's bytes and any empty ancestor
+  // directories it managed. It mutates disk directly (not deferred), because
+  // uninstall deliberately keeps the pre-ADR-2026-08-18 ordering: see the
+  // comment in mutate() for why this is not simetrized with
+  // planArtifactWrite. Mirrors internal/integrations/manager.go:applyUninstall.
+  applyUninstall({ plan, file }, manifest) {
+    const record = manifest.artifacts[file]
+    const key = claimKey(plan.claim)
+    const owned = Boolean(record && record.claims.some(claim => claimKey(claim) === key))
+    if (!owned) return
+    record.claims = record.claims.filter(claim => claimKey(claim) !== key)
+    if (record.claims.length) return
+    if (fs.existsSync(file)) fs.unlinkSync(file)
+    delete manifest.artifacts[file]
+    this.cleanEmpty(path.dirname(file), this.roots[plan.claim.scope])
+  }
+
+  // planArtifactWrite computes the manifest update for one install/update
+  // item entirely in memory — it never touches the artifact's bytes on disk.
+  // The caller (mutate) persists every manifest in the batch first, and only
+  // then applies the returned pending write (ADR-2026-08-18). Returns null
+  // when no byte write is needed.
+  //
+  // The manifest values it stores are deliberately *optimistic* when a write
+  // is pending: sha256/catalog_version describe the content this call is
+  // about to write, not what is currently on disk. If interrupted before the
+  // pending write lands, the manifest already declares the target state and
+  // inspectResolved resolves the (absent or stale) file to
+  // 'not-installed'/'modified', both self-repairable by a later
+  // install/update, never modified+unowned ("unmanaged"). Mirrors
+  // internal/integrations/manager.go:planArtifactWrite.
+  planArtifactWrite(operation, { plan, file }, manifest, force) {
     let record = manifest.artifacts[file]
     const key = claimKey(plan.claim)
     const owned = Boolean(record && record.claims.some(claim => claimKey(claim) === key))
-    if (operation === 'uninstall') {
-      if (!owned) return
-      record.claims = record.claims.filter(claim => claimKey(claim) !== key)
-      if (record.claims.length) return
-      if (fs.existsSync(file)) fs.unlinkSync(file)
-      delete manifest.artifacts[file]
-      this.cleanEmpty(path.dirname(file), this.roots[plan.claim.scope])
-      return
-    }
 
     const exists = fs.existsSync(file)
     let actual = exists ? sha256(fs.readFileSync(file)) : ''
@@ -265,16 +353,29 @@ class IntegrationManager {
     if (exists && !owned) writeDesired = (operation === 'update' && actual !== desired) || (force && actual !== desired)
     else if (exists && owned) writeDesired = actual !== desired
     if (!record) record = { destination: file, sha256: '', catalog_version: '', claims: [] }
+    let pending = null
     if (writeDesired) {
-      this.atomicWrite(file, plan.content, 0o644)
+      // Optimistic: bytes have not moved yet, but the manifest must already
+      // describe the content we are about to write (see doc comment above).
       actual = desired
+      pending = { file, content: plan.content, mode: 0o644 }
     } else if (exists && !owned && actual !== desired && !knownLegacy && !force) {
-      throw new Error(`Unmanaged artifact does not match a trackfw template: ${file}`)
+      // Defense-in-depth: preflight already rejects this exact case for
+      // 'update' (unconditionally) and for 'install' without --force (any
+      // state === 'modified' is blocked before an active item ever reaches
+      // planArtifactWrite()). This branch is therefore not reachable via
+      // install/update today, but stays as a second line of defense in case
+      // preflight's guard is ever loosened — hence the identical remediation
+      // text, so a user who somehow hits it still gets the same actionable
+      // message. No manifest mutation happens on this path. Mirrors
+      // internal/integrations/manager.go:planArtifactWrite.
+      throw new Error(this.unmanagedArtifactError(file, plan.claim))
     }
     if (!record.claims.some(claim => claimKey(claim) === key)) record.claims.push(cleanClaim(plan.claim))
     record.sha256 = actual
     record.catalog_version = actual === desired ? plan.catalogVersion : 'legacy'
     manifest.artifacts[file] = record
+    return pending
   }
 
   snapshot(snapshots, file) {
@@ -292,6 +393,19 @@ class IntegrationManager {
     }
   }
 
+  // unmanagedArtifactError — mensagem de erro para update/uninstall (ou,
+  // defensivamente, install) recusando bytes que o trackfw não escreveu.
+  // Nomeia o remédio — trackfw did not write these bytes, então a única forma
+  // segura de trazer o artefato sob gestão é `<kind> install --force`, que
+  // explicitamente autoriza adotar/substituir conteúdo unmanaged — com as
+  // flags exatas para reproduzir o claim deste plano (item, target, scope),
+  // prontas para copiar e colar. Espelha
+  // internal/integrations/manager.go:unmanagedArtifactError — fonte canônica
+  // do texto, byte a byte idêntica nos 3 CLIs.
+  unmanagedArtifactError(file, claim) {
+    return `unmanaged artifact "${file}" does not match a trackfw template — trackfw did not write these bytes.\nAdopt it with: trackfw ${claim.kind} install --force --items ${claim.item} --targets ${claim.target} --scope ${claim.scope}`
+  }
+
   // tildeAbbrev — retorna o caminho de exibição abreviado para uso em mensagens
   // de aviso de skip. Espelha internal/integrations/manager.go:tildeAbbrev.
   // - scope global: substitui homeRoot por '~' (via tildeify, com salvaguarda

package/src/lib/fatal-error.js

@@ -0,0 +1,64 @@
+'use strict'
+
+const fs = require('node:fs')
+
+// fatal-error.js — global backstop for errors that escape every commander
+// action (sync or async, since npm/bin/trackfw drives the program via
+// parseAsync()). Installed ONCE at the entrypoint, never per-command:
+// the real leak pattern (REQ-2026-08-16-erro-nao-tratado-no-cli-node-vaza-
+// stack-trace-caminhos-absolutos-e-versao-do-runtime) was per-command —
+// commands that catch internally (e.g. `roadmap move`) already print a
+// clean message via console.error + process.exitCode, but any command that
+// doesn't catch let Node's own uncaught-exception/unhandled-rejection
+// printer dump the full stack, absolute install path and runtime version.
+// A single handler at the entrypoint closes every one of those gaps at
+// once instead of relying on every future command remembering a try/catch.
+//
+// TRACKFW_DEBUG=1 restores the full stack — this must never blind someone
+// who genuinely needs to debug a crash.
+//
+// Writes with fs.writeSync(2, ...) — NOT process.stderr.write() — on
+// purpose: installGlobalHandlers() below calls process.exit() right after
+// this returns, and when stderr is a pipe (exactly what every spawnSync-
+// based test in this repo uses, and what a piped CI log is) Node's stream
+// writes are asynchronous; process.exit() can drop a still-pending write
+// before the OS ever sees it, silently eating the message (failure mode
+// #2 in the REQ: "engolir a mensagem" — worse than the leak this handler
+// exists to fix). fs.writeSync is a raw, synchronous syscall — it cannot
+// race process.exit().
+function reportFatalError(err) {
+  // TRACKFW_DEBUG=1: print the full stack (its first line already is
+  // "Error: <message>", so this is the debug-only superset of the clean
+  // path below, not a duplicate of it).
+  if (process.env.TRACKFW_DEBUG === '1' && err && err.stack) {
+    fs.writeSync(2, `${err.stack}\n`)
+    return
+  }
+  const message = err && err.message !== undefined ? err.message : String(err)
+  fs.writeSync(2, `Error: ${message}\n`)
+}
+
+// installGlobalHandlers — defense in depth beyond the parseAsync().catch()
+// in bin/trackfw. Covers errors that reach the process outside that single
+// promise chain (e.g. a rejection from a detached/floating promise started
+// by a command, or a genuine uncaughtException). Per Node's own contract,
+// once a listener is attached Node no longer prints its default trace and
+// no longer auto-exits — the listener owns both the message and the exit.
+// Both listeners call process.exit() immediately after reportFatalError()
+// returns — safe here specifically because reportFatalError writes
+// synchronously (see comment above); process.exitCode (which waits for the
+// event loop to drain) would be wrong here regardless, since long-running
+// commands (e.g. `serve`) hold the loop open and the process would hang
+// instead of exiting on a genuinely fatal error.
+function installGlobalHandlers() {
+  process.on('unhandledRejection', (err) => {
+    reportFatalError(err)
+    process.exit(1)
+  })
+  process.on('uncaughtException', (err) => {
+    reportFatalError(err)
+    process.exit(1)
+  })
+}
+
+module.exports = { reportFatalError, installGlobalHandlers }

package/src/lib/unknown-command.js

@@ -0,0 +1,82 @@
+'use strict'
+
+// unknown-command.js — canonical cross-CLI "unknown command" message and the
+// shared suggestion algorithm.
+//
+// ADR-2026-08-15-remocao-do-subsistema-de-plugins-em-vez-de-gate-de-binario-de-
+// terceiro.md (D3): argument dispatch to an external `trackfw-<name>` binary was
+// removed together with the plugin subsystem. An unrecognized top-level command
+// now always produces the message below instead — in all three CLIs.
+//
+// The plain (no-transposition) Levenshtein distance and the suggestion-picking
+// rule here are reimplemented IDENTICALLY in Go (internal/commands/root.go,
+// suggestCommand/levenshteinDistance) and Python (pypi/trackfw/cli.py,
+// _suggest_command/_levenshtein_distance) — deliberately NOT delegated to each
+// framework's own suggestion helper (cobra's Command.SuggestionsFor, commander's
+// suggestSimilar), which use different distance functions/thresholds and would
+// make the three CLIs disagree on whether/what to suggest for the same typo.
+// Parity is enforced by scripts/check-unknown-command-parity.sh.
+
+function levenshteinDistance(a, b) {
+  const la = a.length
+  const lb = b.length
+  const d = []
+  for (let i = 0; i <= la; i++) {
+    d.push(new Array(lb + 1).fill(0))
+    d[i][0] = i
+  }
+  for (let j = 0; j <= lb; j++) {
+    d[0][j] = j
+  }
+  for (let i = 1; i <= la; i++) {
+    for (let j = 1; j <= lb; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      d[i][j] = Math.min(
+        d[i - 1][j] + 1, // deletion
+        d[i][j - 1] + 1, // insertion
+        d[i - 1][j - 1] + cost, // substitution
+      )
+    }
+  }
+  return d[la][lb]
+}
+
+// suggestCommand — a candidate is eligible when its case-insensitive
+// Levenshtein distance to `typed` is <= 2, OR it is a case-insensitive prefix
+// match (candidate starts with the typed text). Among eligible candidates the
+// winner is the one with the lowest distance, alphabetical tie-break, so the
+// pick is deterministic and single — matching Go/Python exactly.
+function suggestCommand(typed, candidates) {
+  const lowerTyped = typed.toLowerCase()
+  let bestDist = -1
+  let best = ''
+  for (const candidate of candidates) {
+    const lowerC = candidate.toLowerCase()
+    const dist = levenshteinDistance(lowerTyped, lowerC)
+    const prefixMatch = lowerTyped.length > 0 && lowerC.startsWith(lowerTyped)
+    if (dist > 2 && !prefixMatch) continue
+    if (bestDist === -1 || dist < bestDist || (dist === bestDist && candidate < best)) {
+      bestDist = dist
+      best = candidate
+    }
+  }
+  return bestDist === -1 ? null : best
+}
+
+// formatUnknownCommandError — canonical message, byte-identical across the
+// three CLIs modulo the typed name and the suggestion (present only when
+// suggestCommand finds an eligible candidate):
+//   Error: unknown command "x" for "trackfw"
+//   Did you mean "validate"?
+//   Run 'trackfw --help' for usage.
+function formatUnknownCommandError(typed, candidates, cmdPath) {
+  const lines = [`Error: unknown command "${typed}" for "${cmdPath}"`]
+  const suggestion = suggestCommand(typed, candidates)
+  if (suggestion) {
+    lines.push(`Did you mean "${suggestion}"?`)
+  }
+  lines.push(`Run '${cmdPath} --help' for usage.`)
+  return lines.join('\n')
+}
+
+module.exports = { levenshteinDistance, suggestCommand, formatUnknownCommandError }