trackfw 3.1.0 → 5.0.0

package/README.md

@@ -150,6 +150,7 @@ trackfw ship -m "feat(auth): add login flow"
 | `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) |
@@ -164,7 +165,6 @@ trackfw ship -m "feat(auth): add login flow"
 | `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
@@ -330,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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "3.1.0",
+  "version": "5.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,386 @@
+'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}`)
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Wave label grammar (pinned by docs/cli-parity.md, "Wave label grammar" section)
+// ────────────────────────────────────────────────────────────────────────────
+
+// Scan regex (mirrors Go's waveHeadingRe): catches any "## Wave <token> " line.
+// The trailing space is part of rule 1 — a heading whose label touches EOL is not
+// recognised as a wave heading (neither valid nor malformed).
+const WAVE_SCAN_RE = /^## Wave (\S+) /
+
+// Grammar: <integer>[-<suffix>] where integer >= 1 and suffix is [a-z0-9]+ (lowercase).
+// Valid: 1, 2, 2-bis, 2-hotfix, 10-a2.
+// Invalid: X, 2-BIS, -bis, 2-, 2-bis-ter, 0.
+const WAVE_LABEL_RE = /^(\d+)(?:-([a-z0-9]+))?$/
+
+// isValidWaveLabel returns true iff token matches the grammar above.
+// Exported so unit tests can assert the full table of valid/invalid examples.
+function isValidWaveLabel(token) {
+  const m = WAVE_LABEL_RE.exec(String(token))
+  if (!m) return false
+  return parseInt(m[1], 10) >= 1
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Roadmap parsing rules (string-level, see docs/cli-parity.md)
+// ────────────────────────────────────────────────────────────────────────────
+
+// findWave locates the `## Wave <label> ` heading matching waveLabel and returns its
+// line range [startLine, endLine) within `lines`. Performs a full pre-pass over all
+// wave headings (mirroring Go's parseWaves): throws UsageError for the first malformed
+// heading regardless of position — this ensures a typo like `## Wave X — ...` aborts
+// the entire document (ADR decision 16, non-vacuity). Throws UsageError naming the
+// wave label and the resolved roadmap basename when not found (pinned literally by
+// docs/cli-parity.md). roadmapBasename is optional so unit tests that only exercise
+// parsing can omit it; the CLI path always supplies it.
+function findWave(lines, waveLabel, roadmapBasename) {
+  // Pre-pass: validate ALL wave headings and collect them.
+  // Abort immediately on the first malformed heading — this is intentional and
+  // mirrors Go's parseWaves() full-scan approach (ADR decision 16).
+  const waves = []
+  for (let i = 0; i < lines.length; i++) {
+    const attempt = WAVE_SCAN_RE.exec(lines[i])
+    if (!attempt) continue
+    const token = attempt[1]
+    if (!isValidWaveLabel(token)) {
+      throw new UsageError(`malformed wave heading at line ${i + 1}: "${token}" is not a valid wave label`)
+    }
+    let endLine = lines.length
+    for (let j = i + 1; j < lines.length; j++) {
+      if (/^## /.test(lines[j])) { endLine = j; break }
+    }
+    waves.push({ label: token, startLine: i, endLine })
+  }
+
+  // Find the requested wave by exact label match (no prefix/fuzzy matching).
+  const wave = waves.find(w => w.label === String(waveLabel))
+  if (!wave) {
+    throw new UsageError(`wave ${waveLabel} not found in roadmap "${roadmapBasename}"`)
+  }
+  return { startLine: wave.startLine, endLine: wave.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, waveLabel) {
+  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 ${waveLabel}: 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')
+  }
+  const waveLabel = String(waveOption).trim()
+  if (!isValidWaveLabel(waveLabel)) {
+    throw new UsageError(`invalid --wave "${waveOption}" — not a valid wave label`)
+  }
+
+  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, waveLabel, resolved.basename)
+  const mls = findMLs(lines, wave.startLine, wave.endLine)
+  const gates = parseGates(lines, wave.startLine, wave.endLine)
+
+  const checks = []
+  checks.push(evalMlsComplete(mls, waveLabel))
+  checks.push(evalAcceptanceEvidence(mls))
+  checks.push(evalGates(gates.commands, process.cwd()))
+  checks.push(await evalValidate())
+  const finishedAt = new Date()
+
+  const doc = buildDoc(resolved.basename, waveLabel, 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 <label>', 'Wave label to evaluate (e.g. 1, 2-bis, 2-hotfix)')
+    .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.isValidWaveLabel = isValidWaveLabel
+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/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

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

package/src/commands/init.js

@@ -61,9 +61,12 @@ cmd.action(async (options, command) => {
     const supported = new Set(['claude', 'codex', 'gemini', 'antigravity', 'cursor', 'copilot', 'windsurf', 'amazonq', 'kiro'])
     // Sem TTY, o escopo nunca é perguntado: default `global` (ADR D1/D4).
     const scope = await resolveScope({}, { interactive: false })
+    const makeOnSkip = () => (_destination, reason) => {
+      process.stderr.write(`${reason}\n`)
+    }
     for (const tool of aiTools) {
       if (!supported.has(tool)) throw new Error(`Unsupported AI tool: ${tool}`)
-      await generators.installIntegrationTarget(tool, process.cwd(), scope)
+      await generators.installIntegrationTarget(tool, process.cwd(), scope, { onSkip: makeOnSkip() })
     }
     console.log(`\n${t('init.success')}`)
     require('../generators/init').printArchitectNextSteps(process.cwd())
@@ -277,7 +280,12 @@ cmd.action(async (options, command) => {
   const cfg = { projectName, projectType, frontend, backend, backendFramework, pkgManager, hooks, ci, forge: forgeValue || '', requireReqInCommit }
   await generators.scaffold(cfg)
 
-  for (const tool of (aiTools || [])) await generators.installIntegrationTarget(tool, process.cwd(), scope)
+  for (const tool of (aiTools || [])) {
+    const onSkip = (_destination, reason) => {
+      process.stderr.write(`${reason}\n`)
+    }
+    await generators.installIntegrationTarget(tool, process.cwd(), scope, { onSkip })
+  }
 
   console.log(`\n${t('init.success')}`)
   require('../generators/init').printArchitectNextSteps(process.cwd())

package/src/commands/integrations.js

@@ -183,6 +183,15 @@ function createLifecycleCommand(kind) {
       // operações de mutação (install/update/uninstall) e fora de --json.
       if (mutation) printResolvedDestinations(kind, options)
 
+      // Ligar onSkip: aviso em stderr por artefato outdated+owned pulado pelo
+      // preflight de install (contrato: docs/cli-parity.md, seção "install
+      // sobre artefato gerenciado desatualizado — skip, não erro fatal").
+      if (mutation) {
+        options.onSkip = (_destination, reason) => {
+          process.stderr.write(`${reason}\n`)
+        }
+      }
+
       const output = execute(kind, operation, options)
       console.log(options.json ? JSON.stringify(output) : human(output))
     })