trackfw 7.6.0 → 8.0.0-rc2

package/src/commands/baseline.js

@@ -1,13 +0,0 @@
-'use strict'
-const { Command } = require('commander')
-const { validateUnfiltered, saveBaseline } = require('../validator')
-
-const cmd = new Command('baseline')
-cmd.description('Grava snapshot das violations atuais em .trackfw-baseline.json')
-cmd.action(async () => {
-  const { violations, warnings } = await validateUnfiltered()
-  saveBaseline(violations, warnings)
-  console.log(`Baseline gravado: ${violations.length} violations, ${warnings.length} warnings`)
-})
-
-module.exports = cmd

package/src/commands/branch.js

@@ -1,98 +0,0 @@
-'use strict'
-
-// trackfw branch new <type>/<slug>
-//
-// CLI wiring for the `trackfw branch` command group. The testable logic lives in
-// ../branch/runner.js (mirrors the ship.js / ship/runner.js split already used in this CLI).
-
-const { Command } = require('commander')
-const { runBranchNew } = require('../branch/runner')
-const { runBranchPrune } = require('../branch/prune')
-
-function createBranchCommand() {
-  const cmd = new Command('branch')
-  cmd.description('Manage governed feature branches')
-
-  const newCmd = new Command('new')
-  newCmd
-    .description(
-      '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, 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"               # flat project\n' +
-      '  trackfw req new --agent <agent> "title"  # by_agent project with 2+ agents\n' +
-      '  trackfw roadmap new "title"               # flat project\n' +
-      '  trackfw roadmap new --agent <agent> "title"  # by_agent project with 2+ agents\n' +
-      '  trackfw roadmap move <name> wip'
-    )
-    .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, {})
-      if (exitCode !== 0) {
-        process.exit(exitCode)
-      }
-    })
-
-  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
-}
-
-module.exports = createBranchCommand()

package/src/commands/changelog.js

@@ -1,29 +0,0 @@
-'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

@@ -1,66 +0,0 @@
-'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 commits staged changes directly, but blocks the commit before it\n" +
-      'happens when governance is missing, instead of letting it land and only catching it later.\n\n' +
-      'Compositional vocabulary:\n' +
-      '  trackfw commit -m "..."   commits\n' +
-      '  trackfw push              pushes\n' +
-      '  trackfw ship -m "..."     commit + push + PR (composition)\n\n' +
-      'Behavioral steps:\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"               # flat project\n' +
-      '  trackfw req new --agent <agent> "title"  # by_agent project with 2+ agents\n' +
-      '  trackfw roadmap new "title"               # flat project\n' +
-      '  trackfw roadmap new --agent <agent> "title"  # by_agent project with 2+ agents\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/configure.js

@@ -1,106 +0,0 @@
-'use strict'
-const { Command } = require('commander')
-const readline = require('readline')
-const fs = require('fs')
-const path = require('path')
-
-const DEFAULTS = {
-  adr_dirs: 'docs/adr',
-  req_dir: 'docs/req',
-  roadmap_dir: 'docs/roadmaps',
-  wip_limit: '1',
-  link_req: 'REQ:'
-}
-
-/**
- * Pergunta ao usuário via readline e retorna a resposta como Promise<string>.
- * Se o usuário pressionar Enter sem digitar nada, retorna o valor padrão.
- * @param {readline.Interface} rl
- * @param {string} question
- * @param {string} defaultValue
- * @returns {Promise<string>}
- */
-function ask(rl, question, defaultValue) {
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      resolve(answer.trim() || defaultValue)
-    })
-  })
-}
-
-/**
- * Executa o wizard interativo e grava trackfw.yaml.
- * Exportada separadamente para facilitar testes.
- * @param {readline.Interface} [rl] — opcional; se não fornecido, cria um novo
- * @param {string} [cwd] — diretório de trabalho (padrão: process.cwd())
- * @returns {Promise<{ fieldsWritten: number, filePath: string }>}
- */
-async function runConfigure(rl, cwd) {
-  const dir = cwd || process.cwd()
-  const yamlPath = path.join(dir, 'trackfw.yaml')
-  let ownRl = false
-
-  if (!rl) {
-    rl = readline.createInterface({ input: process.stdin, output: process.stdout })
-    ownRl = true
-  }
-
-  try {
-    // Verificar se já existe e perguntar se recria
-    if (fs.existsSync(yamlPath)) {
-      const answer = await ask(rl, 'trackfw.yaml já existe. Recriar do zero? (s/N) ', 'N')
-      if (answer.toLowerCase() !== 's') {
-        console.log('Operação cancelada.')
-        return { fieldsWritten: 0, filePath: yamlPath }
-      }
-    }
-
-    // Coletar campos via prompts
-    const adrDirs = await ask(rl, `ADR dirs [${DEFAULTS.adr_dirs}]: `, DEFAULTS.adr_dirs)
-    const reqDir = await ask(rl, `REQ dir [${DEFAULTS.req_dir}]: `, DEFAULTS.req_dir)
-    const roadmapDir = await ask(rl, `Roadmap dir [${DEFAULTS.roadmap_dir}]: `, DEFAULTS.roadmap_dir)
-    const wipLimit = await ask(rl, `WIP limit [${DEFAULTS.wip_limit}]: `, DEFAULTS.wip_limit)
-    const linkReq = await ask(rl, `Marcador de REQ [${DEFAULTS.link_req}]: `, DEFAULTS.link_req)
-
-    // Montar campos customizados (somente diferenças dos defaults)
-    const custom = {}
-    if (adrDirs !== DEFAULTS.adr_dirs) custom.adr_dirs = adrDirs
-    if (reqDir !== DEFAULTS.req_dir) custom.req_dir = reqDir
-    if (roadmapDir !== DEFAULTS.roadmap_dir) custom.roadmap_dir = roadmapDir
-    if (wipLimit !== DEFAULTS.wip_limit) custom.wip_limit = wipLimit
-    if (linkReq !== DEFAULTS.link_req) custom['link_fields.req'] = linkReq
-
-    // Gerar conteúdo do YAML
-    let content = '# trackfw.yaml — gerado por trackfw configure\n'
-    const fieldsWritten = Object.keys(custom).length
-
-    if (fieldsWritten > 0) {
-      for (const [key, value] of Object.entries(custom)) {
-        if (key === 'adr_dirs') {
-          content += `adr_dirs:\n  - ${value}\n`
-        } else if (key === 'link_fields.req') {
-          content += `link_fields:\n  req:\n    - "${value}"\n`
-        } else {
-          content += `${key}: ${value}\n`
-        }
-      }
-    }
-
-    fs.writeFileSync(yamlPath, content, 'utf8')
-    console.log(`trackfw.yaml gravado com ${fieldsWritten} campos customizados`)
-
-    return { fieldsWritten, filePath: yamlPath }
-  } finally {
-    if (ownRl) rl.close()
-  }
-}
-
-const cmd = new Command('configure')
-cmd.description('Wizard interativo para criar/atualizar trackfw.yaml')
-cmd.action(async () => {
-  await runConfigure()
-})
-
-module.exports = cmd
-module.exports.runConfigure = runConfigure
-module.exports.DEFAULTS = DEFAULTS

package/src/commands/context.js

@@ -1,215 +0,0 @@
-'use strict'
-
-const { Command } = require('commander')
-const fs = require('fs')
-const path = require('path')
-const config = require('../config')
-const { validate, resolveAgentNamespaces, resolveReqFiles } = require('../validator')
-
-/**
- * extractFrontmatterField — extrai valor de campo YAML dentro de bloco --- ... ---.
- * Retorna string vazia se não encontrado ou valor '""'.
- * @param {string} content
- * @param {string} field
- * @returns {string}
- */
-function extractFrontmatterField(content, field) {
-  const lines = content.split('\n')
-  let started = false
-  let inFrontmatter = false
-  for (const line of lines) {
-    const trimmed = line.trim()
-    if (trimmed === '---') {
-      if (!started) {
-        started = true
-        inFrontmatter = true
-        continue
-      }
-      break // segundo --- fecha o bloco
-    }
-    if (!inFrontmatter) break
-    const key = field + ':'
-    if (trimmed.startsWith(key)) {
-      let val = trimmed.slice(key.length).trim()
-      val = val.replace(/^["']|["']$/g, '') // remover aspas
-      return val
-    }
-  }
-  return ''
-}
-
-/**
- * extractInlineStatus — extrai status da linha "| Status: ..." do markdown.
- * @param {string} content
- * @returns {string}
- */
-function extractInlineStatus(content) {
-  for (const line of content.split('\n')) {
-    const idx = line.indexOf('| Status: ')
-    if (idx >= 0) {
-      let rest = line.slice(idx + '| Status: '.length)
-      const pipeIdx = rest.indexOf(' |')
-      if (pipeIdx >= 0) rest = rest.slice(0, pipeIdx)
-      rest = rest.replace(/[\s>|]+$/, '').trim()
-      return rest || 'unknown'
-    }
-  }
-  return 'unknown'
-}
-
-/**
- * collectEntries — lê diretório e retorna lista de entradas com type, file, status, state.
- * @param {string} dir
- * @param {string} type - 'ADR' | 'REQ' | 'ROADMAP'
- * @param {string} [state] - estado kanban (somente ROADMAP)
- * @returns {Array<{type: string, file: string, status: string, state?: string}>}
- */
-function collectEntries(dir, type, state) {
-  const entries = []
-  let files = []
-  try {
-    files = fs.readdirSync(dir).filter(f => f.endsWith('.md') && !fs.statSync(path.join(dir, f)).isDirectory())
-  } catch (_) {
-    return entries
-  }
-  for (const file of files) {
-    let content = ''
-    try { content = fs.readFileSync(path.join(dir, file), 'utf8') } catch (_) {}
-    let status = extractFrontmatterField(content, 'status')
-    if (!status) status = extractInlineStatus(content)
-    if (!status) status = state || 'unknown'
-    const entry = { type, file, status }
-    if (state) entry.state = state
-    entries.push(entry)
-  }
-  return entries
-}
-
-/**
- * collectReqEntries — entradas de REQ para o `context`, derivadas do ponto único de leitura
- * (resolveReqFiles). O `state` sai do nome da pasta-pai quando ela é um estado legado; em layout
- * flat ou no canônico req_dir/<agente>/*.md não há estado (invariante D1: REQ não tem estado).
- * @param {object} cfg
- * @returns {Array<{type:string,file:string,status:string,state?:string}>}
- */
-function collectReqEntries(cfg) {
-  const STATES = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']
-  const entries = []
-  for (const full of resolveReqFiles(cfg)) {
-    let content = ''
-    try { content = fs.readFileSync(full, 'utf8') } catch (_) {}
-    const parent = path.basename(path.dirname(full))
-    const state = STATES.includes(parent) ? parent : ''
-    let status = extractFrontmatterField(content, 'status')
-    if (!status) status = extractInlineStatus(content)
-    if (!status) status = state || 'unknown'
-    const entry = { type: 'REQ', file: path.basename(full), status }
-    if (state) entry.state = state
-    entries.push(entry)
-  }
-  return entries
-}
-
-/**
- * getContext — coleta governança e imprime em md ou json.
- * @param {string} format - 'md' | 'json'
- * @returns {Promise<void>}
- */
-async function getContext(format) {
-  const cfg = config.load()
-
-  // ADRs
-  const adrs = []
-  for (const adrDir of (cfg.adrDirs || ['docs/adr'])) {
-    adrs.push(...collectEntries(adrDir, 'ADR'))
-  }
-
-  // REQs — pelo PONTO ÚNICO de leitura (ADR-2026-09-03, D3/D4). Antes, `context` montava a própria
-  // árvore (flat, ou <agente>/<estado>/ em by_agent) e não enxergava o layout canônico <agente>/*.md.
-  const reqs = collectReqEntries(cfg)
-
-  // Roadmaps
-  const roadmaps = []
-  const states = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
-  if (cfg.roadmapNamespacing === 'by_agent') {
-    const agents = resolveAgentNamespaces(cfg, cfg.roadmapDir)
-    for (const agent of agents) {
-      for (const state of states) {
-        const dir = path.join(cfg.roadmapDir, agent, state)
-        roadmaps.push(...collectEntries(dir, 'ROADMAP', state))
-      }
-    }
-  } else {
-    for (const state of states) {
-      const dir = path.join(cfg.roadmapDir, state)
-      roadmaps.push(...collectEntries(dir, 'ROADMAP', state))
-    }
-  }
-
-  // Validate
-  const { violations, warnings } = await validate()
-
-  // Score
-  let score = 0
-  if (adrs.length > 0) score += 20
-  if (reqs.length > 0) score += 20
-  if (roadmaps.length > 0) score += 20
-  if (violations.length === 0) score += 40
-
-  if (format === 'json') {
-    console.log(JSON.stringify({ score, violations, warnings, adrs, reqs, roadmaps }, null, 2))
-    return
-  }
-
-  // Markdown
-  console.log('# trackfw governance context\n')
-  console.log(`**Governance score:** ${score}/100\n`)
-
-  console.log(`## ADRs (${adrs.length})`)
-  if (adrs.length === 0) {
-    console.log('- (none)')
-  } else {
-    for (const a of adrs) console.log(`- ${a.file} [${a.status}]`)
-  }
-
-  console.log(`\n## REQs (${reqs.length})`)
-  if (reqs.length === 0) {
-    console.log('- (none)')
-  } else {
-    for (const r of reqs) console.log(`- ${r.file} [${r.status}]`)
-  }
-
-  console.log(`\n## Roadmaps (${roadmaps.length})`)
-  if (roadmaps.length === 0) {
-    console.log('- (none)')
-  } else {
-    for (const r of roadmaps) console.log(`- ${r.file} [${r.state}]`)
-  }
-
-  if (violations.length > 0) {
-    console.log(`\n## Violations (${violations.length})`)
-    for (const v of violations) console.log(`- ${v}`)
-  }
-
-  if (warnings.length > 0) {
-    console.log(`\n## Warnings (${warnings.length})`)
-    for (const w of warnings) console.log(`- ${w}`)
-  }
-}
-
-module.exports = (function () {
-  const cmd = new Command('context')
-  cmd
-    .description('Print governance context for LLM consumption')
-    .option('--format <fmt>', 'Output format: md or json', 'md')
-    // Retorna a Promise: o bin roda parseAsync() e só assim uma rejeição chega
-    // ao .catch(reportFatalError) com exit code 1 em vez de virar unhandled
-    // rejection (ML-1A, ROADMAP-2026-09-02-context-do-cli-node-aguarda-validate).
-    .action((opts) => getContext(opts.format))
-  return cmd
-})()
-
-// Exposto para teste: o teste de context em by_agent duplicava a lógica de coleta e, por isso,
-// continuava verde mesmo quando a produção mudava (asserção sobre uma CÓPIA). Anexar a função ao
-// Command exportado é o menor caminho para o teste exercitar o código de produção de fato.
-module.exports.collectReqEntries = collectReqEntries