trackfw 6.10.0 → 7.1.0

package/src/changelog/index.js

@@ -0,0 +1,114 @@
+'use strict'
+
+// changelog — parsing e extração de seções do CHANGELOG.md no formato
+// Keep a Changelog (https://keepachangelog.com/en/1.1.0/).
+// Port 1:1 de internal/changelog/changelog.go — manter em sincronia.
+
+const fs = require('fs')
+const path = require('path')
+
+// sectionHeaderRE casa cabeçalhos de seção no formato "## [x.y.z] - YYYY-MM-DD"
+// ou "## [Unreleased]" (sem data).
+const sectionHeaderRE = /^## \[([^\]]+)\](?: - (\d{4}-\d{2}-\d{2}))?/
+
+/**
+ * parseSections — separa o conteúdo de um CHANGELOG.md em seções, uma por
+ * cabeçalho "## [...]" encontrado. Texto antes da primeira seção (título do
+ * arquivo, preâmbulo) é descartado.
+ * @param {string} content
+ * @returns {Array<{version: string, date: string, body: string}>}
+ */
+function parseSections(content) {
+  const lines = content.split('\n')
+
+  const sections = []
+  let current = null
+  let bodyLines = []
+
+  const flush = () => {
+    if (current !== null) {
+      current.body = bodyLines.join('\n')
+      sections.push(current)
+    }
+  }
+
+  for (const line of lines) {
+    const m = sectionHeaderRE.exec(line)
+    if (m !== null) {
+      flush()
+      current = { version: m[1], date: m[2] || '', body: '' }
+      bodyLines = []
+      continue
+    }
+    if (current !== null) {
+      bodyLines.push(line)
+    }
+  }
+  flush()
+
+  return sections
+}
+
+/**
+ * firstSection — retorna a primeira seção da lista.
+ * Erro se a lista vier vazia.
+ * @param {Array<{version: string, date: string, body: string}>} sections
+ * @returns {{version: string, date: string, body: string}}
+ */
+function firstSection(sections) {
+  if (sections.length === 0) {
+    throw new Error('CHANGELOG.md has no version sections')
+  }
+  return sections[0]
+}
+
+/**
+ * findVersion — busca a seção com version igual ao argumento, normalizando um
+ * prefixo "v"/"V" opcional no argumento do usuário antes de comparar.
+ * @param {Array<{version: string, date: string, body: string}>} sections
+ * @param {string} version
+ * @returns {{version: string, date: string, body: string}}
+ */
+function findVersion(sections, version) {
+  let normalized = version
+  if (normalized.length > 0 && (normalized[0] === 'v' || normalized[0] === 'V')) {
+    normalized = normalized.slice(1)
+  }
+  for (const s of sections) {
+    if (s.version === normalized || s.version === version) {
+      return s
+    }
+  }
+  throw new Error(`version "${version}" not found in CHANGELOG.md`)
+}
+
+/**
+ * formatSection — reconstrói o texto formatado de uma seção, reproduzindo o
+ * cabeçalho original.
+ * @param {{version: string, date: string, body: string}} section
+ * @returns {string}
+ */
+function formatSection(section) {
+  const dateSuffix = section.date !== '' ? ` - ${section.date}` : ''
+  const body = section.body.replace(/^\n+/, '')
+  return `## [${section.version}]${dateSuffix}\n\n${body.replace(/\n+$/, '') + '\n'}`
+}
+
+/**
+ * read — lê o CHANGELOG.md na raiz informada.
+ * @param {string} root
+ * @returns {string}
+ */
+function read(root) {
+  const filePath = path.join(root, 'CHANGELOG.md')
+  try {
+    return fs.readFileSync(filePath, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error('CHANGELOG.md not found — nothing to show')
+    }
+    throw err
+  }
+}
+
+module.exports = { parseSections, firstSection, findVersion, formatSection, read }

package/src/commands/branch.js

@@ -7,6 +7,7 @@
 
 const { Command } = require('commander')
 const { runBranchNew } = require('../branch/runner')
+const { runBranchPrune } = require('../branch/prune')
 
 function createBranchCommand() {
   const cmd = new Command('branch')
@@ -15,22 +16,25 @@ function createBranchCommand() {
   const newCmd = new Command('new')
   newCmd
     .description(
-      'Create a feat/fix/refactor branch, gated on a matching REQ + roadmap already in wip/ or done/\n\n' +
+      'Create a feat/fix/refactor/chore/docs branch; feat/fix/refactor gated on a matching REQ + roadmap already in wip/ or done/\n\n' +
       'trackfw branch new moves the branch_has_wip_roadmap governance gate (already enforced\n' +
       "by 'trackfw validate' and 'trackfw ship') to before branch creation, instead of after:\n\n" +
-      '  1. Validates <type> is one of feat, fix, refactor and <slug> is non-empty.\n' +
-      '  2. Checks whether a roadmap in wip/ or done/ matches the given slug — the exact matching\n' +
-      "     logic 'trackfw validate' already uses (normalized slug, filename contains match).\n" +
-      "  3. Without a match: blocks — 'git checkout -b' is never executed — and prints the same\n" +
-      "     governance orientation message 'trackfw validate' already prints for this rule.\n" +
-      "  4. With a match: runs 'git checkout -b <type>/<slug>', propagating Git's own output and\n" +
-      '     exit status literally.\n\n' +
+      '  1. Validates <type> is one of feat, fix, refactor, chore, docs and <slug> is non-empty.\n' +
+      '  2. For feat, fix, refactor: checks whether a roadmap in wip/ or done/ matches the given\n' +
+      "     slug — the exact matching logic 'trackfw validate' already uses (normalized slug,\n" +
+      "     filename contains match). Without a match: blocks — 'git checkout -b' is never\n" +
+      "     executed — and prints the same governance orientation message 'trackfw validate'\n" +
+      "     already prints for this rule.\n" +
+      "  3. For chore, docs: housekeeping types already treated as roadmap-exempt by 'trackfw ship'\n" +
+      "     and 'trackfw commit' — the branch is created without the roadmap gate.\n" +
+      "  4. With a match (or for chore/docs): runs 'git checkout -b <type>/<slug>', propagating\n" +
+      "     Git's own output and exit status literally.\n\n" +
       'Create the governance artifacts first if this blocks you:\n' +
       '  trackfw req new "title"\n' +
       '  trackfw roadmap new "title"\n' +
       '  trackfw roadmap move <name> wip'
     )
-    .argument('<spec>', '<type>/<slug>, type in feat, fix, refactor')
+    .argument('<spec>', '<type>/<slug>, type in feat, fix, refactor, chore, docs')
     .option('--dry-run', 'Report whether the branch would be created or blocked, without executing git', false)
     .action((spec, options) => {
       const exitCode = runBranchNew(spec, !!options.dryRun, {})
@@ -40,6 +44,52 @@ function createBranchCommand() {
     })
 
   cmd.addCommand(newCmd)
+
+  const pruneCmd = new Command('prune')
+  pruneCmd
+    .description('Report (and, with --apply, delete) local branches already integrated into origin/main')
+    .addHelpText(
+      'after',
+      '\n' +
+      'trackfw branch prune automates the "one active branch at a time" check documented in\n' +
+      'CLAUDE.md §1 — it does not remove human judgment from every case: a branch whose only\n' +
+      'remaining divergence is doc/config files is flagged for manual review, never deleted\n' +
+      'automatically.\n\n' +
+      "A best-effort 'git fetch origin --prune' runs first. Failure (offline, no remote) is\n" +
+      'non-blocking: a warning is printed and evaluation proceeds against the local origin/main\n' +
+      'ref, whatever its state. A stale origin/main only ever makes the result MORE conservative —\n' +
+      'it can miss a branch that was in fact integrated since the last fetch (reporting it kept\n' +
+      'when a fresh fetch would show it deletable), but it never reports one as deletable that a\n' +
+      'fresh fetch would show as pending.\n\n' +
+      "Decides integration with the touched-files heuristic, NOT git's own ancestry check (which\n" +
+      'always refuses squash-merged branches) and NOT a naive bidirectional diff against origin/main\n' +
+      '(which false-positives on a branch that is merged but stale, once main has advanced further):\n\n' +
+      '  mb      = git merge-base origin/main <branch>\n' +
+      '  touched = git diff --name-only mb <branch>                 (what the branch touched)\n' +
+      '  diverg  = git diff --name-only origin/main <branch> -- touched  (what still differs there)\n\n' +
+      'touched empty          -> integrated (safe to delete)\n' +
+      'diverg empty           -> integrated (safe to delete) -- squash-merged, stale, main advanced since\n' +
+      'diverg doc/config only -> flagged for review (kept; probable housekeeping, confirm and delete manually)\n' +
+      'otherwise               -> kept, with the diverging files named\n\n' +
+      'Every local branch is reported, always, with its decision and reason. The current branch, any\n' +
+      'branch checked out in another worktree, and the default branch (main) are always kept and\n' +
+      'never evaluated for deletion. Without origin/main resolvable at all (offline with no prior\n' +
+      'fetch ever having run, or no remote configured), the whole command refuses and deletes\n' +
+      'nothing.\n\n' +
+      '--dry-run is the default: without --apply, nothing is ever deleted, even the clearly\n' +
+      "integrated. Deletion tries 'git branch -d' first — confirming the integration via git's own\n" +
+      "ancestry check too, when possible — and falls back to 'git branch -D' only when -d refuses,\n" +
+      'the expected case for squash-merged branches, which never have fast-forward ancestry with main.'
+    )
+    .option('--apply', 'Actually delete branches decided as integrated (default: report only, delete nothing)', false)
+    .action((options) => {
+      const exitCode = runBranchPrune(!!options.apply, {})
+      if (exitCode !== 0) {
+        process.exit(exitCode)
+      }
+    })
+
+  cmd.addCommand(pruneCmd)
   return cmd
 }
 

package/src/commands/changelog.js

@@ -0,0 +1,29 @@
+'use strict'
+const { Command } = require('commander')
+const { read, parseSections, firstSection, findVersion, formatSection } = require('../changelog')
+
+const cmd = new Command('changelog')
+cmd.description('Show entries from CHANGELOG.md')
+// enablePositionalOptions escopa a flag local "--version" a este subcomando,
+// evitando que o root a intercepte como a flag global "trackfw --version".
+cmd.enablePositionalOptions()
+cmd.option('--version <x.y.z>', 'Show a specific version section')
+cmd.option('--all', 'Show the entire CHANGELOG.md')
+cmd.action(async (opts) => {
+  try {
+    const root = process.cwd()
+    const content = read(root)
+    if (opts.all) {
+      process.stdout.write(content)
+      return
+    }
+    const sections = parseSections(content)
+    const section = opts.version ? findVersion(sections, opts.version) : firstSection(sections)
+    process.stdout.write(formatSection(section))
+  } catch (err) {
+    console.error(`Error: ${err.message}`)
+    process.exitCode = 1
+  }
+})
+
+module.exports = cmd

package/src/commands/commit.js

@@ -0,0 +1,60 @@
+'use strict'
+
+// trackfw commit -m "<message>"
+//
+// CLI wiring for the `trackfw commit` command. The testable logic lives in
+// ../commit/runner.js (mirrors the branch.js / branch/runner.js split already used in this CLI).
+
+const { Command } = require('commander')
+const { runCommit, buildSuggestedMessage } = require('../commit/runner')
+
+function createCommitCommand() {
+  const cmd = new Command('commit')
+  cmd
+    .description(
+      "trackfw commit is the missing intermediate step between raw 'git commit' and\n" +
+      "'trackfw ship': it commits staged changes directly, but blocks the commit before it happens\n" +
+      'when governance is missing, instead of letting it land and only catching it later:\n\n' +
+      "  1. On 'main'/'master': always blocked — commit directly on the default branch is never\n" +
+      '     permitted.\n' +
+      '  2. On a feat/fix/refactor branch: requires a roadmap matching the branch slug already in\n' +
+      "     wip/ or done/ — the exact matching logic 'trackfw branch new' and 'trackfw validate'\n" +
+      '     already use. Without a match, blocks with the same governance orientation message.\n' +
+      '  3. On any other branch (e.g. doc/housekeeping branches): allowed without requiring a\n' +
+      '     roadmap — a warning is logged, but the commit proceeds.\n' +
+      "  4. When allowed: runs 'git commit -m <message>', propagating Git's own output and exit\n" +
+      '     status literally.\n\n' +
+      "'--suggest' takes a completely separate path: it prints a heuristic Conventional Commits\n" +
+      "skeleton built from 'git diff --cached --name-status' (type + staged file list) and exits\n" +
+      'without ever committing — no LLM call, just a structural heuristic. It is not a\n' +
+      'ready-to-use message; review and edit before using it with -m. When \'--suggest\' is set,\n' +
+      "'-m' (if also passed) is ignored and no commit ever happens.\n\n" +
+      'Create the governance artifacts first if this blocks you:\n' +
+      '  trackfw req new "title"\n' +
+      '  trackfw roadmap new "title"\n' +
+      '  trackfw roadmap move <name> wip'
+    )
+    .option('-m, --message <msg>', 'Commit message (required)')
+    .option('--suggest', 'Print a heuristic Conventional Commits message skeleton from staged files and exit without committing (ignores -m)')
+    .action((options) => {
+      if (options.suggest) {
+        try {
+          const suggestion = buildSuggestedMessage({})
+          process.stdout.write(suggestion + '\n')
+          return
+        } catch (err) {
+          process.stderr.write(err.message + '\n')
+          process.exit(1)
+        }
+      }
+
+      const exitCode = runCommit(options.message || '', {})
+      if (exitCode !== 0) {
+        process.exit(exitCode)
+      }
+    })
+
+  return cmd
+}
+
+module.exports = createCommitCommand()

package/src/commands/discover.js

@@ -22,6 +22,11 @@ function scan(rootDir) {
     hookFramework: 'none',
     ciSystem: 'none',
     forge: '',
+    // suggestedTestFramework é uma sugestão best-effort (nunca erro, '' quando nada bate) baseada
+    // em arquivos de configuração presentes na raiz do projeto. É apenas impressa como sugestão
+    // pelo comando `discover` — nunca escrita automaticamente em trackfw.yaml (a convenção de
+    // agent_conventions deve ser sempre declarada pelo time, não inferida).
+    suggestedTestFramework: '',
   };
 
   // trackfw.yaml
@@ -110,6 +115,9 @@ function scan(rootDir) {
     r.ciSystem = 'none';
   }
 
+  // Suggested test framework — best-effort heuristic, never an error.
+  r.suggestedTestFramework = detectTestFramework(rootDir);
+
   // Forge detection — reuse forge/resolve.js (no duplicate parse).
   // gitRemoteURL returns '' on any error; CI detection is filesystem-based.
   try {
@@ -338,6 +346,60 @@ function countMD(dir) {
   return n;
 }
 
+// detectTestFramework é uma heurística best-effort para sugerir um framework de teste com base
+// em arquivos de configuração presentes na raiz do projeto. Nunca retorna erro — retorna '' quando
+// nenhum arquivo-gatilho é encontrado. Ordem de precedência: jest, vitest, pytest, go test.
+function detectTestFramework(rootDir) {
+  if (isFile(path.join(rootDir, 'jest.config.js')) || isFile(path.join(rootDir, 'jest.config.ts'))) {
+    return 'jest';
+  }
+  if (isFile(path.join(rootDir, 'vitest.config.js')) || isFile(path.join(rootDir, 'vitest.config.ts'))) {
+    return 'vitest';
+  }
+  if (isFile(path.join(rootDir, 'pytest.ini'))) {
+    return 'pytest';
+  }
+  if (hasFileWithSubstring(path.join(rootDir, 'pyproject.toml'), '[tool.pytest')) {
+    return 'pytest';
+  }
+  if (hasFileWithSubstring(path.join(rootDir, 'setup.cfg'), '[tool:pytest]')) {
+    return 'pytest';
+  }
+  if (isFile(path.join(rootDir, 'go.mod')) && hasGoTestFile(rootDir)) {
+    return 'go test';
+  }
+  return '';
+}
+
+// hasFileWithSubstring lê path e retorna true se seu conteúdo contém sub. Retorna false
+// silenciosamente se o arquivo não existir ou não puder ser lido (best-effort).
+function hasFileWithSubstring(p, sub) {
+  let content;
+  try { content = fs.readFileSync(p, 'utf8'); } catch { return false; }
+  return content.includes(sub);
+}
+
+// hasGoTestFile percorre rootDir recursivamente procurando qualquer arquivo *_test.go.
+function hasGoTestFile(rootDir) {
+  let found = false;
+  function walk(d) {
+    if (found) return;
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (found) return;
+      if (e.isDirectory()) {
+        walk(path.join(d, e.name));
+      } else if (e.name.endsWith('_test.go')) {
+        found = true;
+        return;
+      }
+    }
+  }
+  walk(rootDir);
+  return found;
+}
+
 function listSubDirs(dir) {
   try {
     return fs.readdirSync(dir).filter(f => {
@@ -412,6 +474,12 @@ cmd.action((opts) => {
     console.log('⚠ No CI system detected');
   }
 
+  // suggested test framework — printed only, never written to trackfw.yaml automatically
+  // (agent_conventions must always be declared by the team).
+  if (r.suggestedTestFramework) {
+    console.log(`Suggested test framework: ${r.suggestedTestFramework} (add to trackfw.yaml as agent_conventions: if correct)`);
+  }
+
   console.log(`\nGovernance Score: ${r.governanceScore}/100`);
 
   if (opts.init) {
@@ -447,6 +515,12 @@ cmd.action((opts) => {
       } catch (e) {
         console.warn(`⚠ credential guard script: ${e.message}`);
       }
+      try {
+        const { generateGitBranchGuardScript } = require('../generators/hooks');
+        generateGitBranchGuardScript(cwd);
+      } catch (e) {
+        console.warn(`⚠ git branch guard script: ${e.message}`);
+      }
       try {
         const { injectHooksDetected } = require('../generators/hooks');
         injectHooksDetected(cwd);
@@ -500,3 +574,4 @@ module.exports.generateBootstrapLog = generateBootstrapLog;
 module.exports.writeValidateScript = writeValidateScript;
 module.exports.writeCIWorkflow = writeCIWorkflow;
 module.exports.writeCIWorkflowForce = writeCIWorkflowForce;
+module.exports.detectTestFramework = detectTestFramework;

package/src/commands/doctor.js

@@ -0,0 +1,32 @@
+'use strict'
+
+const { Command } = require('commander')
+const { runDoctor, UNREGISTERED_WRITE, HAND_MODIFIED, UNKNOWN_CONTENT } = require('../integrations/doctor')
+
+function printReport(findings) {
+  if (findings.length === 0) {
+    return 'trackfw doctor: no mismatches found -- disk matches the manifest for every catalog-managed artifact.'
+  }
+  const unregistered = findings.filter(finding => finding.finding === UNREGISTERED_WRITE).length
+  const handModified = findings.filter(finding => finding.finding === HAND_MODIFIED).length
+  const unknownContent = findings.filter(finding => finding.finding === UNKNOWN_CONTENT).length
+  const lines = [`trackfw doctor: ${findings.length} finding(s) -- ${unregistered} unregistered-write, ${handModified} hand-modified, ${unknownContent} unknown-content`, '']
+  for (const finding of findings) {
+    lines.push(`[${finding.finding}] ${finding.destination}`, `  remedy: ${finding.remedy}`, '')
+  }
+  return lines.join('\n').replace(/\n$/, '')
+}
+
+const cmd = new Command('doctor')
+cmd.description('Detect artifacts on disk missing from the manifest, distinguishing hand-modified artifacts from unknown content')
+cmd.option('--json', 'Emit findings as a JSON array instead of the text report')
+cmd.action(async options => {
+  const findings = runDoctor({})
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(findings, null, 2)}\n`)
+    return
+  }
+  process.stdout.write(`${printReport(findings)}\n`)
+})
+
+module.exports = cmd

package/src/commands/index.js

@@ -2,6 +2,7 @@
 
 const { Command } = require('commander')
 const { version } = require('../../package.json')
+const { formatUnknownCommandError } = require('../lib/unknown-command')
 
 function createProgram() {
   const program = new Command()
@@ -9,6 +10,25 @@ function createProgram() {
     .name('trackfw')
     .description('trackfw — governed software delivery framework\nADR → REQ → ROADMAP → kanban')
     .version(`trackfw ${version}`)
+  // enablePositionalOptions: garante que uma flag de subcomando (ex.: o
+  // "changelog --version <x.y.z>") não seja capturada pela flag global
+  // "--version" do root — sem isto, commander casa "--version" contra o
+  // primeiro registro conhecido em toda a árvore de comandos.
+  program.enablePositionalOptions()
+
+  // Comando desconhecido — mensagem canônica compartilhada pelos 3 CLIs
+  // (ADR-2026-08-15-remocao-do-subsistema-de-plugins-em-vez-de-gate-de-binario-
+  // de-terceiro.md D3). Registrar um listener 'command:*' intercepta ANTES do
+  // commander chamar seu próprio Command.unknownCommand() — evita reformatar
+  // uma mensagem já impressa por ele (o padrão que causava dupla-impressão no
+  // Go, ver internal/commands/root.go) e evita depender do texto/threshold
+  // próprio de commander.suggestSimilar, que diverge de cobra/argparse.
+  program.on('command:*', (operands) => {
+    const typed = operands[0]
+    const candidates = program.commands.map((cmd) => cmd.name())
+    process.stderr.write(formatUnknownCommandError(typed, candidates, program.name()) + '\n')
+    process.exit(1)
+  })
 
   program.addCommand(require('./init'))
   program.addCommand(require('./adr'))
@@ -16,8 +36,8 @@ function createProgram() {
   program.addCommand(require('./roadmap'))
   program.addCommand(require('./validate'))
   program.addCommand(require('./status'))
+  program.addCommand(require('./changelog'))
   program.addCommand(require('./log'))
-  program.addCommand(require('./plugins'))
   program.addCommand(require('./discover'))
   program.addCommand(require('./update'))
   program.addCommand(require('./metrics'))
@@ -33,13 +53,12 @@ function createProgram() {
   program.addCommand(require('./ship'))
   program.addCommand(require('./barrier'))
   program.addCommand(require('./branch'))
+  program.addCommand(require('./commit'))
+  program.addCommand(require('./doctor'))
 
   const { createServeCommand } = require('./serve')
   program.addCommand(createServeCommand())
 
-  // plugin dispatch — comandos desconhecidos tentam executar plugin
-  program.hook('preSubcommand', () => {})
-
   return program
 }
 

package/src/commands/integrations.js

@@ -6,10 +6,26 @@ const { catalog, execute, parseSurfaces, buildPlans } = require('../integrations
 const identityStore = require('../identity')
 const identityWizard = require('./identity-wizard')
 const { t } = require('../i18n')
+const { createThirdPartyCommand } = require('./thirdparty')
 
 const csv = value => String(value).split(',').map(entry => entry.trim()).filter(Boolean)
 const collect = (value, previous) => previous.concat(value)
 
+// forceHelp returns the --force help text for a mutation subcommand. The
+// three operations grant --force different powers, and a single shared
+// string previously overstated update/uninstall's reach while never
+// mentioning install's ability to adopt unmanaged bytes — that ambiguity is
+// what sent a user straight into the "Unmanaged artifact does not match a
+// trackfw template" error on `update --force` (see unmanagedArtifactError in
+// src/integrations/manager.js for the matching remediation). Mirrors
+// internal/commands/integrations_flags.go:forceHelp and
+// pypi/trackfw/integrations/command.py.
+function forceHelp(operation) {
+  if (operation === 'install') return 'Replace a modified managed artifact, or adopt/overwrite an unmanaged file already on disk'
+  if (operation === 'uninstall') return 'Remove a modified managed artifact'
+  return "Replace a modified managed artifact; never adopts unmanaged bytes — use 'install --force' for that"
+}
+
 function human(result) {
   const lines = [`Available ${result.kind} (catalog ${result.catalog_version}):`]
   for (const item of result.items) lines.push(`  ${item.id.padEnd(14)} ${item.name} — ${item.description}`)
@@ -102,6 +118,12 @@ async function promptAmbiguousSurfaces(kind, options, prompts = require('@inquir
 
 function createLifecycleCommand(kind) {
   const root = new Command(kind).description(`Manage trackfw ${kind}`)
+  // third-party fetch/install (D1): reachable from both `trackfw agents
+  // third-party` and `trackfw skills third-party`, under the same
+  // two-phase quarantine gate. Mirrors
+  // internal/commands/integrations_flags.go registering `third-party` in
+  // newIntegrationsLifecycleCmd.
+  root.addCommand(createThirdPartyCommand(kind))
   for (const operation of ['list', 'install', 'uninstall', 'update']) {
     const mutation = operation !== 'list'
     const command = new Command(operation)
@@ -110,7 +132,7 @@ function createLifecycleCommand(kind) {
       .option('--scope <scope>', 'Installation scope: project or global (default: global; asks interactively)')
       .option('--surface <target=surface>', 'Surface selection (repeatable)', collect, [])
       .option('--json', 'Print deterministic JSON')
-      .option('--force', 'Replace or remove modified artifacts')
+      .option('--force', forceHelp(operation))
 
     // Flags de identidade são exclusivas de agents (ADR D5): skills não têm
     // identidade, e createLifecycleCommand é compartilhado entre `agents` e

package/src/commands/serve.js

@@ -13,6 +13,48 @@ const { handleAttention } = require('../serve/api_attention')
 
 const STATIC_DIR = path.join(__dirname, '..', 'serve', 'static')
 
+// Aviso pinado, byte-idêntico entre os 3 runtimes (Go, Node.js, Python) — ver
+// docs/cli-parity.md "`trackfw serve` — endereço de escuta, `--host` e
+// aviso de exposição". Emitido quando --host resolve para uma interface
+// diferente de loopback.
+function exposureWarning(host, port) {
+  return `WARNING: trackfw serve is binding to ${host}:${port} — the governance chain (ADRs, REQs, roadmaps) will be readable without authentication by any device that can reach it.`
+}
+
+// Texto de --help pinado, byte-idêntico entre os 3 runtimes.
+const SERVE_HOST_FLAG_HELP = 'Host to bind to (loopback only by default; use 0.0.0.0 to expose on the network)'
+
+// Espelha internal/serve/serve.go IsLoopbackHost — 'localhost' ou IP loopback
+// (IPv4 127.0.0.0/8 inteiro, ou IPv6 ::1), igual a net.IP.IsLoopback() do Go
+// e ipaddress.ip_address(...).is_loopback do Python.
+function isLoopbackHost(host) {
+  const net = require('net')
+  if (host === 'localhost') return true
+  if (net.isIPv4(host)) {
+    return host.split('.')[0] === '127'
+  }
+  if (net.isIPv6(host)) {
+    return host === '::1' || host === '0:0:0:0:0:0:0:1'
+  }
+  return false
+}
+
+// Espelha internal/serve/serve.go DisplayURL — URL a imprimir e a abrir no
+// browser. 'localhost' é mantido só para 'localhost' ou IPv4 loopback
+// (127.0.0.0/8), para não mudar a saída do caso comum; hosts IPv6 usam
+// colchetes; qualquer outro host é impresso como está.
+function displayUrl(host, port) {
+  const net = require('net')
+  if (host === 'localhost') return `http://localhost:${port}`
+  if (net.isIPv4(host)) {
+    return host.split('.')[0] === '127' ? `http://localhost:${port}` : `http://${host}:${port}`
+  }
+  if (net.isIPv6(host)) {
+    return `http://[${host}]:${port}`
+  }
+  return `http://${host}:${port}`
+}
+
 // Mapa de extensão → Content-Type
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -141,19 +183,25 @@ function createServeCommand() {
   cmd
     .description('Inicia o servidor HTTP do trackfw dashboard (kanban + chain + metrics)')
     .option('--port <port>', 'Porta do servidor', '8080')
+    .option('--host <host>', SERVE_HOST_FLAG_HELP, '127.0.0.1')
     .option('--no-open', 'Não abrir o browser automaticamente')
     .action((opts) => {
       const cfg = config.load()
       const port = parseInt(opts.port, 10) || 8080
+      const host = opts.host
 
       const server = createServer(cfg, port)
 
-      server.listen(port, '127.0.0.1', () => {
-        console.log(`trackfw serve: http://localhost:${port}`)
+      if (!isLoopbackHost(host)) {
+        console.error(exposureWarning(host, port))
+      }
+
+      server.listen(port, host, () => {
+        const url = displayUrl(host, port)
+        console.log(`trackfw serve: ${url}`)
 
         if (opts.open !== false) {
           // Tentar abrir o browser
-          const url = `http://localhost:${port}`
           const { exec } = require('child_process')
           const platform = process.platform
           let openCmd
@@ -187,4 +235,4 @@ function createServeCommand() {
   return cmd
 }
 
-module.exports = { createServeCommand, createServer }
+module.exports = { createServeCommand, createServer, isLoopbackHost, displayUrl }

package/src/commands/ship.js

@@ -9,9 +9,10 @@ function createShipCommand() {
   cmd
     .description(
       'trackfw ship runs a governed delivery sequence:\n\n' +
-      '  1. Validates branch name — must match feat|fix|refactor/<slug>\n' +
-      '  2. Validates governance — REQ + roadmap in wip/ must exist\n' +
-      '     (hard gate: not affected by lenient mode or per-rule severity)\n' +
+      '  1. Validates branch name — must match feat|fix|refactor|chore|docs/<slug>\n' +
+      '  2. Validates governance — REQ + roadmap in wip/ must exist for feat/fix/refactor branches\n' +
+      '     (hard gate: not affected by lenient mode or per-rule severity); chore/docs branches skip\n' +
+      "     this check, mirroring 'trackfw commit'\n" +
       '  3. Detects pending squash-merges in other branches (advisory only)\n' +
       '  4. Reviews what is staged (git status --short + git diff --cached --stat)\n' +
       '  5. Commits with Conventional Commits format (-m is required)\n' +