trackfw 3.0.0 → 4.0.0

package/README.md

@@ -128,6 +128,10 @@ trackfw validate
 
 # 6. See what is in flight
 trackfw status
+
+# 7. Governed commit + push + open PR/MR (feat/fix/refactor branches only)
+git add -p                        # stage your changes explicitly
+trackfw ship -m "feat(auth): add login flow"
 ```
 
 ---
@@ -146,6 +150,8 @@ trackfw status
 | `trackfw roadmap move <name> <state>` | Move roadmap between states |
 | `trackfw roadmap list` | List all roadmaps grouped by state |
 | `trackfw validate` | Check governance consistency (use as CI gate) |
+| `trackfw barrier <roadmap> --wave <n>` | Deterministic wave-release gate — stack-agnostic, checks MLs, acceptance evidence, project-declared gates, and governance |
+| `trackfw ship -m "msg"` | Governed `git commit + push + open PR/MR` — enforces branch pattern and governance gate; resolves forge (GitHub/GitLab/Bitbucket/Azure) automatically or via `--forge`; falls back to a browser URL when the forge CLI is absent |
 | `trackfw context` | Print a structured summary of the project's governance state (REQs, Roadmaps, ADRs with counts and statuses) |
 | `trackfw serve` | Start a local governance dashboard (no cloud, no accounts) |
 | `trackfw status` | Show wip, blocked, REQs waiting on ADRs |
@@ -159,7 +165,6 @@ trackfw status
 | `trackfw agents uninstall` | Remove selected owned agent deployments |
 | `trackfw skills list` | List available governance skills and deployment state |
 | `trackfw skills install/update/uninstall` | Manage selected governance skills |
-| `trackfw gemini`, `cursor`, `copilot`, `windsurf`, `amazonq` | Historical aliases in the Go distribution only; use `agents`/`skills` |
 | `trackfw version` | Print version |
 
 The same lifecycle contract is available from the Go/Homebrew, npm, and PyPI
@@ -325,6 +330,90 @@ $ trackfw status
 
 ---
 
+## `trackfw barrier` — deterministic wave-release gate
+
+```bash
+trackfw barrier <roadmap> --wave <n> [--json]
+```
+
+`trackfw barrier` is the stack-agnostic core of the wave-release gate: it never assumes a build
+tool, a test runner, or a parity rule. Every check either comes from the roadmap itself (the wave's
+declared gates) or from `trackfw validate` run in-process. Point it at a roadmap basename (with or
+without `.md`, resolved against `wip/` then `done/`) and a wave number, and it tells you whether
+that wave is ready to release.
+
+A wave passes only when **all four** built-in checks are green:
+
+| Check | Passes when |
+|---|---|
+| `mls_complete` | The wave has at least one ML and every ML is marked `**Status:** ✅` |
+| `acceptance_evidence` | Every ML has a non-empty `**Critérios de aceite:**` block with no unchecked `- [ ]` line |
+| `gates` | Every command declared under the wave's `**Gates da wave:**` fenced block exits 0 — a wave with no such block declares zero gates, and the barrier never invents one |
+| `validate` | `trackfw validate --json` reports `violations: 0` |
+
+### Exit codes
+
+| Exit | Meaning |
+|---|---|
+| `0` | `status: "passed"` — every check is green, the wave may release |
+| `1` | `status: "blocked"` — at least one check failed; the JSON/text report says which |
+| `2` | Usage/resolution error — the roadmap or the wave number could not be resolved. This is **not** `blocked`: a barrier that could not run is distinct from one that ran and failed |
+
+### Correcting a blocked wave
+
+```bash
+$ trackfw barrier ROADMAP-example --wave 2
+✗ mls_complete: ML-2C: not complete (status: 🔄)
+✗ acceptance_evidence: ML-2C: 2 unmet acceptance criteria
+wave 2: blocked
+```
+
+Fix the roadmap (mark the ML `✅`, check off the remaining criteria) and rerun the exact same
+command — the barrier is not a one-shot denial; a corrected wave passes on the next invocation:
+
+```bash
+$ trackfw barrier ROADMAP-example --wave 2
+✓ mls_complete
+✓ acceptance_evidence
+✓ gates
+✓ validate
+wave 2: passed
+```
+
+### JSON output
+
+```bash
+trackfw barrier ROADMAP-example --wave 2 --json
+```
+
+```json
+{
+  "roadmap": "ROADMAP-example.md",
+  "wave": 2,
+  "status": "blocked",
+  "started_at": "2026-07-29T10:30:00Z",
+  "finished_at": "2026-07-29T10:30:04Z",
+  "checks": [
+    { "name": "mls_complete", "status": "passed", "evidence": ["ML-2A: ✅"], "failures": [] },
+    { "name": "acceptance_evidence", "status": "blocked", "evidence": [], "failures": ["ML-2C: 2 unmet acceptance criteria"] },
+    { "name": "gates", "status": "passed", "commands": ["make quality"], "evidence": ["make quality: exit 0"], "failures": [] },
+    { "name": "validate", "status": "passed", "evidence": ["0 violations, 0 warnings"], "failures": [] }
+  ],
+  "failures": ["acceptance_evidence: ML-2C: 2 unmet acceptance criteria"]
+}
+```
+
+### `trackfw barrier` vs. `/trackfw:barrier`
+
+`trackfw barrier` is the deterministic, reproducible CLI — it never invokes agents and never
+performs Git operations. The `/trackfw:barrier` slash command wraps it with the parts a binary
+cannot evaluate: dispatching `code-quality`/`security` reviews, auditing the diff against scope,
+and — only for `trackfw_architect`, the sole Git authority in this workflow — committing and
+pushing once every check and review is green. A green CLI barrier is necessary but not sufficient
+to release a wave. Full contract: `docs/cli-parity.md` → `## trackfw barrier`.
+
+---
+
 ## AI assistant integration
 
 `trackfw init` can install initial AI integrations. The `agents` and `skills`
@@ -372,14 +461,16 @@ operation could delete artifacts from the user's home directory. `list` never
 prompts and always assumes `global` unless `--scope` is given, so it reports
 the same destinations `install` actually wrote to.
 
-The 10 roles installed for each tool: **architect · backend · frontend · qa · infra · security · code-quality · dba · ux · data**
+The **12 roles** installed for each tool: **architect · backend · frontend · qa · infra · security · code-quality · dba · ux · data · iac · tooling**
+
+The **17 skills** cover governance process (governance, implement, plan, release, review) and technical specialties (backend-skill, code-quality-skill, data-skill, dba-skill, frontend-skill, iac-skill, infra-skill, qa-skill, security-skill, tooling-skill, ux-skill, vault-skill).
 
 ---
 
 ## Agent identity — give your agents a name
 
 By default the agents are functional and impersonal: `trackfw-architect`,
-`trackfw-backend`, … Agent identity lets you name all ten, pick how they
+`trackfw-backend`, … Agent identity lets you name all twelve, pick how they
 address you, and call them by name.
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, and Amazon Q.",
   "keywords": [
     "cli",

package/src/commands/barrier.js

@@ -0,0 +1,358 @@
+'use strict'
+
+// trackfw barrier <roadmap> --wave <n> [--json]
+//
+// Deterministic core of the wave-release barrier. Stack-agnostic: every executable
+// check comes from the roadmap itself (see docs/cli-parity.md → `## trackfw barrier`).
+// This command never assumes a build tool, a test runner or a parity rule, and it
+// never performs git operations or invokes specialist agents — that orchestration
+// lives in the `/trackfw:barrier` slash command.
+
+const { Command } = require('commander')
+const fs = require('fs')
+const path = require('path')
+const { spawnSync } = require('child_process')
+const config = require('../config')
+const validator = require('../validator')
+
+// UsageError signals a resolution/parsing failure that must map to exit code 2 —
+// distinct from a "blocked" (exit 1) evaluation result.
+class UsageError extends Error {}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Roadmap resolution
+// ────────────────────────────────────────────────────────────────────────────
+
+// resolveRoadmapFile finds <roadmapArg> (basename with or without .md) under
+// wip/ then done/ (both flat and by_agent layouts). Throws UsageError naming the
+// roadmap exactly as the user typed it (no .md normalization) when not found —
+// pinned literally by docs/cli-parity.md (`## trackfw barrier`).
+function resolveRoadmapFile(cfg, roadmapArg) {
+  const base = roadmapArg.endsWith('.md') ? roadmapArg : `${roadmapArg}.md`
+  const dirs = [...validator.resolveWIPDirs(cfg), ...validator.resolveDoneDirs(cfg)]
+  for (const dir of dirs) {
+    const candidate = path.join(config.expandPath(dir), base)
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return { path: candidate, basename: base }
+    }
+  }
+  throw new UsageError(`roadmap "${roadmapArg}" not found in wip/ nor done/ under ${cfg.roadmapDir}`)
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Roadmap parsing rules (string-level, see docs/cli-parity.md)
+// ────────────────────────────────────────────────────────────────────────────
+
+// findWave locates the `## Wave <n> ` heading matching waveNumber and returns its
+// line range [startLine, endLine) within `lines`. Throws UsageError naming the wave
+// number and the resolved roadmap basename when not found (pinned literally by
+// docs/cli-parity.md), or naming the offending line number for a malformed heading.
+// roadmapBasename is optional so existing unit tests that only exercise parsing can
+// omit it; the CLI path always supplies it.
+function findWave(lines, waveNumber, roadmapBasename) {
+  let startLine = -1
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const attempt = /^## Wave (\S+)/.exec(line)
+    if (!attempt) continue
+    if (!/^\d+$/.test(attempt[1])) {
+      throw new UsageError(`malformed wave heading at line ${i + 1}: "${line}"`)
+    }
+    if (parseInt(attempt[1], 10) === waveNumber) {
+      startLine = i
+      break
+    }
+  }
+  if (startLine === -1) {
+    throw new UsageError(`wave ${waveNumber} not found in roadmap "${roadmapBasename}"`)
+  }
+  let endLine = lines.length
+  for (let j = startLine + 1; j < lines.length; j++) {
+    if (/^## /.test(lines[j])) { endLine = j; break }
+  }
+  return { startLine, endLine }
+}
+
+// findMLs locates every `### ML-` heading inside [startLine, endLine) and returns
+// { id, lines } for each, where `lines` is the ML body (heading excluded).
+function findMLs(lines, startLine, endLine) {
+  const headings = []
+  for (let i = startLine; i < endLine; i++) {
+    if (/^### ML-/.test(lines[i])) {
+      const m = /^### (\S+)/.exec(lines[i])
+      headings.push({ id: m[1], headingLine: i })
+    }
+  }
+  return headings.map((h, idx) => {
+    let end = endLine
+    for (let j = h.headingLine + 1; j < endLine; j++) {
+      if (/^### /.test(lines[j]) || /^## /.test(lines[j])) { end = j; break }
+    }
+    return { id: h.id, lines: lines.slice(h.headingLine + 1, end) }
+  })
+}
+
+// mlCompletionStatus applies rule 3 — completion is a `**Status:**` line whose
+// remainder contains ✅. Returns { complete, marker } where marker is "missing"
+// when no `**Status:**` line exists at all.
+function mlCompletionStatus(mlLines) {
+  for (const raw of mlLines) {
+    const line = raw.trim()
+    const m = /^\*\*Status:\*\*(.*)$/.exec(line)
+    if (m) {
+      const marker = m[1].trim()
+      return { complete: marker.includes('✅'), marker: marker.length > 0 ? marker : 'missing' }
+    }
+  }
+  return { complete: false, marker: 'missing' }
+}
+
+// mlAcceptanceEvidence applies rule 4. Returns { hasBlock, total, unmet }.
+function mlAcceptanceEvidence(mlLines) {
+  let blockStart = -1
+  for (let i = 0; i < mlLines.length; i++) {
+    if (/^\*\*Crit[ée]rios de aceite:\*\*/.test(mlLines[i].trim())) { blockStart = i; break }
+  }
+  if (blockStart === -1) return { hasBlock: false, total: 0, unmet: 0 }
+
+  let blockEnd = mlLines.length
+  for (let j = blockStart + 1; j < mlLines.length; j++) {
+    if (/^\*\*/.test(mlLines[j].trim())) { blockEnd = j; break }
+  }
+
+  const blockLines = mlLines.slice(blockStart + 1, blockEnd)
+    .map(l => l.trim())
+    .filter(l => l.length > 0)
+
+  const criteria = blockLines.filter(l => /^- \[/.test(l))
+  if (criteria.length === 0) return { hasBlock: false, total: 0, unmet: 0 }
+
+  const unmet = criteria.filter(l => /^- \[ \]/.test(l))
+  return { hasBlock: true, total: criteria.length, unmet: unmet.length }
+}
+
+// parseGates applies rule 5. Returns { commands }. Throws UsageError naming the
+// offending line number for an unterminated fence.
+function parseGates(lines, startLine, endLine) {
+  let markerLine = -1
+  for (let i = startLine; i < endLine; i++) {
+    if (lines[i].trim() === '**Gates da wave:**') { markerLine = i; break }
+  }
+  if (markerLine === -1) return { commands: [] }
+
+  let i = markerLine + 1
+  while (i < endLine && lines[i].trim() === '') i++
+  if (i >= endLine || lines[i].trim() !== '```bash') {
+    throw new UsageError(`malformed gates block at line ${markerLine + 1}: expected a \`\`\`bash fence`)
+  }
+
+  const fenceStart = i
+  i++
+  const commands = []
+  let closed = false
+  for (; i < endLine; i++) {
+    const trimmed = lines[i].trim()
+    if (trimmed === '```') { closed = true; break }
+    if (trimmed.length === 0 || trimmed.startsWith('#')) continue
+    commands.push(trimmed)
+  }
+  if (!closed) {
+    throw new UsageError(`unterminated gates fence starting at line ${fenceStart + 1}`)
+  }
+  return { commands }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Checks (fixed evaluation order: mls_complete, acceptance_evidence, gates, validate)
+// ────────────────────────────────────────────────────────────────────────────
+
+function evalMlsComplete(mls, waveNumber) {
+  const evidence = []
+  const failures = []
+  for (const ml of mls) {
+    const { complete, marker } = mlCompletionStatus(ml.lines)
+    if (complete) evidence.push(`${ml.id}: ✅`)
+    else failures.push(`${ml.id}: not complete (status: ${marker})`)
+  }
+  const status = mls.length > 0 && failures.length === 0 ? 'passed' : 'blocked'
+  // Pinned literally by docs/cli-parity.md ("Wave contains zero MLs" case).
+  if (mls.length === 0) failures.push(`wave ${waveNumber}: no ML found`)
+  return { name: 'mls_complete', status, evidence, failures }
+}
+
+function evalAcceptanceEvidence(mls) {
+  const evidence = []
+  const failures = []
+  for (const ml of mls) {
+    const ev = mlAcceptanceEvidence(ml.lines)
+    if (!ev.hasBlock) {
+      failures.push(`${ml.id}: no acceptance block`)
+    } else if (ev.unmet > 0) {
+      failures.push(`${ml.id}: ${ev.unmet} unmet acceptance criteria`)
+    } else {
+      evidence.push(`${ml.id}: ${ev.total} criteria met`)
+    }
+  }
+  const status = failures.length === 0 ? 'passed' : 'blocked'
+  return { name: 'acceptance_evidence', status, evidence, failures }
+}
+
+function evalGates(commands, cwd) {
+  const evidence = []
+  const failures = []
+  for (const command of commands) {
+    const result = spawnSync(command, {
+      shell: true,
+      cwd,
+      encoding: 'utf8',
+      stdio: 'pipe',
+    })
+    const code = result.status === null || result.status === undefined ? 1 : result.status
+    if (code === 0) evidence.push(`${command}: exit 0`)
+    else failures.push(`${command}: exit ${code}`)
+  }
+  const status = failures.length === 0 ? 'passed' : 'blocked'
+  return { name: 'gates', status, commands, evidence, failures }
+}
+
+async function evalValidate() {
+  const { violations, warnings } = await validator.validate()
+  const summary = `${violations.length} violations, ${warnings.length} warnings`
+  if (violations.length === 0) {
+    return { name: 'validate', status: 'passed', evidence: [summary], failures: [] }
+  }
+  return { name: 'validate', status: 'blocked', evidence: [], failures: [summary] }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Result document
+// ────────────────────────────────────────────────────────────────────────────
+
+function isoSeconds(date) {
+  return date.toISOString().replace(/\.\d{3}Z$/, 'Z')
+}
+
+function buildDoc(roadmapBasename, waveNumber, checks, startedAt, finishedAt) {
+  const status = checks.every(c => c.status === 'passed') ? 'passed' : 'blocked'
+  const failures = []
+  for (const check of checks) {
+    for (const f of check.failures) failures.push(`${check.name}: ${f}`)
+  }
+  return {
+    roadmap: roadmapBasename,
+    wave: waveNumber,
+    status,
+    started_at: isoSeconds(startedAt),
+    finished_at: isoSeconds(finishedAt),
+    checks: checks.map(c => {
+      const doc = { name: c.name, status: c.status, evidence: c.evidence, failures: c.failures }
+      if (c.name === 'gates') {
+        return { name: c.name, status: c.status, commands: c.commands, evidence: c.evidence, failures: c.failures }
+      }
+      return doc
+    }),
+    failures,
+  }
+}
+
+function printTextReport(doc) {
+  console.log(`Roadmap: ${doc.roadmap}`)
+  console.log(`Wave:    ${doc.wave}`)
+  console.log(`Status:  ${doc.status}`)
+  console.log('')
+  for (const check of doc.checks) {
+    console.log(`[${check.status}] ${check.name}`)
+    for (const e of check.evidence) console.log(`  ✓ ${e}`)
+    for (const f of check.failures) console.log(`  ✗ ${f}`)
+  }
+  if (doc.failures.length > 0) {
+    console.log('')
+    console.log('Failures:')
+    for (const f of doc.failures) console.log(`  • ${f}`)
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Command
+// ────────────────────────────────────────────────────────────────────────────
+
+async function runBarrier(roadmapArg, waveOption, jsonOutput) {
+  if (waveOption === undefined || waveOption === null || String(waveOption).trim() === '') {
+    throw new UsageError('--wave is required')
+  }
+  if (!/^\d+$/.test(String(waveOption).trim()) || parseInt(waveOption, 10) < 1) {
+    throw new UsageError(`invalid --wave value: "${waveOption}" (must be an integer >= 1)`)
+  }
+  const waveNumber = parseInt(waveOption, 10)
+
+  const cfg = config.load()
+  const resolved = resolveRoadmapFile(cfg, roadmapArg)
+  const content = fs.readFileSync(resolved.path, 'utf8')
+  const lines = content.split('\n')
+
+  const startedAt = new Date()
+  const wave = findWave(lines, waveNumber, resolved.basename)
+  const mls = findMLs(lines, wave.startLine, wave.endLine)
+  const gates = parseGates(lines, wave.startLine, wave.endLine)
+
+  const checks = []
+  checks.push(evalMlsComplete(mls, waveNumber))
+  checks.push(evalAcceptanceEvidence(mls))
+  checks.push(evalGates(gates.commands, process.cwd()))
+  checks.push(await evalValidate())
+  const finishedAt = new Date()
+
+  const doc = buildDoc(resolved.basename, waveNumber, checks, startedAt, finishedAt)
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(doc, null, 2))
+  } else {
+    printTextReport(doc)
+  }
+
+  return doc.status === 'passed' ? 0 : 1
+}
+
+function createBarrierCommand() {
+  const cmd = new Command('barrier')
+  cmd
+    .description(
+      'Deterministic core of the wave-release barrier: evaluates ML completion, ' +
+      'acceptance evidence, wave gates and governance validation for a single wave ' +
+      'declared in a roadmap.'
+    )
+    .argument('<roadmap>', 'Roadmap basename, with or without .md')
+    .option('--wave <n>', 'Wave number to evaluate (integer >= 1)')
+    .option('--json', 'Emit the result document as JSON instead of a text report')
+    .action(async (roadmapArg, options) => {
+      try {
+        const exitCode = await runBarrier(roadmapArg, options.wave, !!options.json)
+        process.exit(exitCode)
+      } catch (err) {
+        if (err instanceof UsageError) {
+          process.stderr.write(`trackfw barrier: ${err.message}\n`)
+          process.exit(2)
+          return
+        }
+        process.stderr.write(`trackfw barrier: unexpected error: ${err && err.message ? err.message : err}\n`)
+        process.exit(2)
+      }
+    })
+
+  return cmd
+}
+
+module.exports = createBarrierCommand()
+module.exports.UsageError = UsageError
+module.exports.resolveRoadmapFile = resolveRoadmapFile
+module.exports.findWave = findWave
+module.exports.findMLs = findMLs
+module.exports.mlCompletionStatus = mlCompletionStatus
+module.exports.mlAcceptanceEvidence = mlAcceptanceEvidence
+module.exports.parseGates = parseGates
+module.exports.evalMlsComplete = evalMlsComplete
+module.exports.evalAcceptanceEvidence = evalAcceptanceEvidence
+module.exports.evalGates = evalGates
+module.exports.evalValidate = evalValidate
+module.exports.buildDoc = buildDoc
+module.exports.runBarrier = runBarrier

package/src/commands/discover.js

@@ -4,6 +4,7 @@ const { Command } = require('commander');
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const { resolve: resolveForge } = require('../forge/resolve');
 
 function scan(rootDir) {
   const r = {
@@ -20,6 +21,7 @@ function scan(rootDir) {
     governanceScore: 0,
     hookFramework: 'none',
     ciSystem: 'none',
+    forge: '',
   };
 
   // trackfw.yaml
@@ -108,6 +110,18 @@ function scan(rootDir) {
     r.ciSystem = 'none';
   }
 
+  // Forge detection — reuse forge/resolve.js (no duplicate parse).
+  // gitRemoteURL returns '' on any error; CI detection is filesystem-based.
+  try {
+    const { resolveFromRepo } = require('../forge/resolve');
+    const res = resolveFromRepo('', '', rootDir);
+    if (res.source !== 'none') {
+      r.forge = res.forge;
+    }
+  } catch (_) {
+    // forge detection is best-effort; never block scan on it
+  }
+
   r.governanceScore = calcScore(r);
   return r;
 }
@@ -146,6 +160,10 @@ function generateYAML(r) {
   out += `hooks: ${r.hookFramework}\n`;
   out += `ci: ${r.ciSystem}\n`;
 
+  if (r.forge) {
+    out += `forge: ${r.forge}\n`;
+  }
+
   return out;
 }
 

package/src/commands/help.js

@@ -247,22 +247,112 @@ function describeKey(key) {
   ].join('\n')
 }
 
+/**
+ * Retorna a listagem de comandos disponíveis a partir do programa raiz.
+ * @param {import('commander').Command} root
+ * @returns {string}
+ */
+function listCommands(root) {
+  const visible = root.commands.filter((sub) => !sub._hidden)
+  const nameWidth = Math.max(...visible.map((sub) => sub.name().length)) + 2
+  const lines = ['Comandos disponíveis:']
+  for (const sub of visible) {
+    lines.push(`  ${sub.name().padEnd(nameWidth)}${sub.description()}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Distância de edição (Levenshtein) entre duas strings.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  const la = a.length
+  const lb = b.length
+  let prev = new Array(lb + 1)
+  let curr = new Array(lb + 1)
+  for (let j = 0; j <= lb; j++) prev[j] = j
+  for (let i = 1; i <= la; i++) {
+    curr[0] = i
+    for (let j = 1; j <= lb; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost)
+    }
+    const tmp = prev
+    prev = curr
+    curr = tmp
+  }
+  return prev[lb]
+}
+
+/**
+ * Retorna o comando ou chave de configuração conhecida mais próxima de
+ * topic (distância de edição <= 3), ou null se nenhuma for próxima o
+ * suficiente.
+ * @param {string} topic
+ * @param {import('commander').Command} root
+ * @returns {string|null}
+ */
+function suggestTopic(topic, root) {
+  const threshold = 3
+  const candidates = [
+    ...root.commands.filter((sub) => !sub._hidden).map((sub) => sub.name()),
+    ...Object.keys(configDocs)
+  ]
+  let best = null
+  let bestDist = threshold + 1
+  for (const candidate of candidates) {
+    const dist = levenshtein(topic, candidate)
+    if (dist < bestDist) {
+      bestDist = dist
+      best = candidate
+    }
+  }
+  return bestDist <= threshold ? best : null
+}
+
 const cmd = new Command('help')
-cmd.description('Exibe documentação das keys configuráveis do trackfw.yaml')
-cmd.argument('[key]', 'key específica para detalhar')
-cmd.action((key) => {
-  if (!key) {
+cmd.description('Exibe ajuda de comandos e documentação das chaves de configuração do trackfw.yaml')
+cmd.argument('[topic]', 'comando ou chave de configuração para detalhar')
+cmd.action(function (topic, options, thisCommand) {
+  const self = thisCommand || this
+  const root = self.parent || self
+
+  if (!topic) {
+    console.log(listCommands(root))
+    console.log()
     console.log(listKeys())
     return
   }
-  const output = describeKey(key)
-  if (!output) {
-    console.error(`chave desconhecida: ${key}`)
-    process.exit(1)
+
+  // 1) comando conhecido → ajuda do comando.
+  const sub = root.commands.find((c) => c.name() === topic)
+  if (sub) {
+    console.log(sub.helpInformation().trimEnd())
+    return
+  }
+
+  // 2) chave de configuração conhecida → documentação da chave.
+  const output = describeKey(topic)
+  if (output) {
+    console.log(output)
+    return
+  }
+
+  // 3) assunto desconhecido → erro com sugestão útil.
+  let msg = `assunto desconhecido: ${topic}`
+  const suggestion = suggestTopic(topic, root)
+  if (suggestion) {
+    msg += `\nVocê quis dizer: ${suggestion}?`
   }
-  console.log(output)
+  console.error(msg)
+  process.exitCode = 1
 })
 
 module.exports = cmd
 module.exports.listKeys = listKeys
 module.exports.describeKey = describeKey
+module.exports.listCommands = listCommands
+module.exports.suggestTopic = suggestTopic

package/src/commands/index.js

@@ -29,6 +29,9 @@ function createProgram() {
   program.addCommand(require('./version'))
   program.addCommand(require('./agents'))
   program.addCommand(require('./skills'))
+  program.addCommand(require('./note'))
+  program.addCommand(require('./ship'))
+  program.addCommand(require('./barrier'))
 
   const { createServeCommand } = require('./serve')
   program.addCommand(createServeCommand())