trackfw 2.16.0 → 3.1.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,7 @@ 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 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 |
@@ -363,14 +368,25 @@ are never replaced or removed unless `--force` is explicit, and unmanaged files
 are never removed. Known historical templates are adopted without overwriting;
 unknown unmanaged content cannot be adopted by `update`, even with `--force`.
 
-The 10 roles installed for each tool: **architect · backend · frontend · qa · infra · security · code-quality · dba · ux · data**
+Without `--scope`, `install`/`update` default to `global` (`~/.claude/...`)
+when stdin is not a TTY, and otherwise prompt interactively with `global`
+pre-selected — the resolved destination paths are printed before anything is
+written. `uninstall` is the one exception: without `--scope` and without a
+TTY it fails instead of guessing, since silently defaulting a destructive
+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 **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": "2.16.0",
+  "version": "3.1.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/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/index.js

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

package/src/commands/init.js

@@ -4,11 +4,13 @@ const { t } = require('../i18n')
 const identityStore = require('../identity')
 const identityWizard = require('./identity-wizard')
 const { resolveIdentityPreset, identityFileExists } = identityWizard
+const { resolveScope } = require('./integrations')
 
 const cmd = new Command('init')
 cmd.description(t('init.description'))
 cmd.option('--ai-tools <tools>', 'Comma-separated AI tools to configure (claude,codex,gemini,antigravity,cursor,copilot,windsurf,amazonq,kiro)', '')
 cmd.option('--identity-preset <preset>', `Agent identity preset: none, neutral, ${identityStore.presetNames().join(', ')}`, 'none')
+cmd.option('--forge <value>', 'Forge platform: github, gitlab, bitbucket, azure', '')
 cmd.action(async (options, command) => {
   const os = require('os')
   const path = require('path')
@@ -28,6 +30,14 @@ cmd.action(async (options, command) => {
     }
   }
 
+  // --forge: validate unconditionally above the non-TTY early return so that
+  // an invalid value fails loudly in CI instead of silently no-op'ing.
+  const forgeChanged = command.getOptionValueSource('forge') === 'cli'
+  if (forgeChanged && options.forge) {
+    const { validateForge } = require('../forge/resolve')
+    validateForge(options.forge) // throws on invalid value
+  }
+
   // Pula o wizard de identidade inteiramente quando a flag foi passada
   // explicitamente (já tratado acima) ou quando um arquivo de identidade já
   // existe — re-executar init nunca deve sobrescrever silenciosamente uma
@@ -44,13 +54,16 @@ cmd.action(async (options, command) => {
       pkgManager: 'npm',
       hooks: 'none',
       ci: 'none',
+      forge: forgeChanged ? options.forge : '',
     }
     await generators.scaffold(cfg)
     const aiTools = String(options.aiTools || '').split(',').map(tool => tool.trim()).filter(Boolean)
     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 })
     for (const tool of aiTools) {
       if (!supported.has(tool)) throw new Error(`Unsupported AI tool: ${tool}`)
-      await generators.installIntegrationTarget(tool, process.cwd())
+      await generators.installIntegrationTarget(tool, process.cwd(), scope)
     }
     console.log(`\n${t('init.success')}`)
     require('../generators/init').printArchitectNextSteps(process.cwd())
@@ -59,7 +72,17 @@ cmd.action(async (options, command) => {
 
   const { input, select, checkbox } = require('@inquirer/prompts')
 
-  let projectName, projectType, frontend, pkgManager, backend, backendFramework, hooks, ci, aiTools, requireReqInCommit
+  // Detect forge from the current dir to prefill the wizard default.
+  const { resolveFromRepo: resolveForgeFromRepo } = require('../forge/resolve')
+  let detectedForge = ''
+  if (!forgeChanged) {
+    try {
+      const res = resolveForgeFromRepo('', '', process.cwd())
+      if (res.source !== 'none') detectedForge = res.forge
+    } catch (_) {}
+  }
+
+  let projectName, projectType, frontend, pkgManager, backend, backendFramework, hooks, ci, forgeValue, aiTools, requireReqInCommit, scope
 
   try {
     projectName = await input({
@@ -160,6 +183,22 @@ cmd.action(async (options, command) => {
       ],
     })
 
+    if (!forgeChanged) {
+      forgeValue = await select({
+        message: t('init.prompt.forge'),
+        default: detectedForge,
+        choices: [
+          { name: 'Auto-detect (omit key)', value: '' },
+          { name: 'GitHub', value: 'github' },
+          { name: 'GitLab', value: 'gitlab' },
+          { name: 'Bitbucket', value: 'bitbucket' },
+          { name: 'Azure DevOps', value: 'azure' },
+        ],
+      })
+    } else {
+      forgeValue = options.forge
+    }
+
     requireReqInCommit = false
     if (hooks !== 'none') {
       const { confirm: confirmPrompt } = require('@inquirer/prompts')
@@ -184,6 +223,11 @@ cmd.action(async (options, command) => {
       ],
     })
 
+    // Escopo de instalação (ADR D4): só pergunta quando há de fato algo para
+    // instalar. `resolveScope` é a mesma função (mesmas strings/mecanismo de
+    // prompt) usada por `agents install` / `skills install`.
+    scope = aiTools.length ? await resolveScope({}, { interactive: true }) : 'global'
+
   } catch (err) {
     // Fallback quando stdin fecha inesperadamente (ex: pipe em TTY simulado)
     const cfg = {
@@ -194,6 +238,7 @@ cmd.action(async (options, command) => {
       pkgManager: 'npm',
       hooks: 'none',
       ci: 'none',
+      forge: forgeChanged ? options.forge : '',
     }
     await generators.scaffold(cfg)
     console.log(`\n${t('init.success')}`)
@@ -221,6 +266,7 @@ cmd.action(async (options, command) => {
         pkgManager: 'npm',
         hooks: 'none',
         ci: 'none',
+        forge: forgeChanged ? options.forge : '',
       })
       console.log(`\n${t('init.success')}`)
       require('../generators/init').printArchitectNextSteps(process.cwd())
@@ -228,10 +274,10 @@ cmd.action(async (options, command) => {
     }
   }
 
-  const cfg = { projectName, projectType, frontend, backend, backendFramework, pkgManager, hooks, ci, requireReqInCommit }
+  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())
+  for (const tool of (aiTools || [])) await generators.installIntegrationTarget(tool, process.cwd(), scope)
 
   console.log(`\n${t('init.success')}`)
   require('../generators/init').printArchitectNextSteps(process.cwd())

package/src/commands/integrations.js

@@ -2,7 +2,7 @@
 
 const os = require('node:os')
 const { Command } = require('commander')
-const { catalog, execute, parseSurfaces } = require('../integrations')
+const { catalog, execute, parseSurfaces, buildPlans } = require('../integrations')
 const identityStore = require('../identity')
 const identityWizard = require('./identity-wizard')
 const { t } = require('../i18n')
@@ -27,6 +27,66 @@ async function promptSelection(kind, options, prompts = require('@inquirer/promp
   options.items = await checkbox({ message: `${kind} to manage`, choices: catalog[kind].map(item => ({ name: item.name, value: item.id })), required: true })
 }
 
+// resolveScope decide o escopo de instalação (ADR-2026-07-25-escopo-de-
+// instalacao-selecionavel-para-agents-e-skills):
+//
+//  - `--scope` explícito (`options.scope !== undefined`) é sempre respeitado
+//    e nunca dispara prompt — apenas validado contra os valores aceitos. A
+//    detecção é por *flag-set* (undefined), nunca por comparação de valor,
+//    para não confundir um `--scope project` explícito com o default.
+//  - Sem flag e `interactive` desligado (comando `list`, D6): default
+//    `global`, nunca lança erro (list nunca é destrutivo).
+//  - Sem flag e stdin não é um TTY (D1): default `global` — exceto para
+//    `uninstall` (ADR D8), que falha exigindo `--scope` explícito. D1 foi
+//    aprovado no enquadramento "onde instalar"; aplicá-lo a uninstall
+//    permitiria que um script de CI que hoje limpa `.claude/agents/` do
+//    repositório passasse a apagar arquivos do home do usuário.
+//  - Sem flag, `interactive` ligado e TTY (D2): pergunta o escopo, com
+//    `global` pré-selecionado, para toda operação incluindo uninstall — o
+//    usuário vê a escolha antes de destruir. Usa o mesmo mecanismo de prompt
+//    (`@inquirer/prompts`) já empregado por `identity-wizard.js`, sem
+//    dependência nova.
+//
+// `interactive` é passado pelo chamador como `false` para `list` — comando de
+// leitura que nunca deve bloquear em prompt, mas que ainda assim precisa do
+// mesmo default `global` para não reportar deployments divergentes dos que o
+// `install` gravou (D6). `operation` identifica install/update/uninstall/list
+// para o branch de D8. Espelha
+// internal/commands/integrations_flags.go:resolveScope.
+async function resolveScope(options, { interactive = true, operation, prompts = require('@inquirer/prompts') } = {}) {
+  if (options.scope !== undefined) {
+    if (options.scope !== 'project' && options.scope !== 'global') throw new Error(`Unsupported scope: ${options.scope}`)
+    return options.scope
+  }
+  if (!interactive) return 'global'
+  if (!process.stdin.isTTY) {
+    if (operation === 'uninstall') throw new Error('uninstall requires --scope in non-interactive mode')
+    return 'global'
+  }
+  const { select } = prompts
+  return select({
+    message: 'Onde instalar os artefatos?',
+    default: 'global',
+    choices: [
+      { name: 'Pasta do usuário (~/.claude) — vale para todos os projetos', value: 'global' },
+      { name: 'Este projeto (.claude) — apenas neste repositório', value: 'project' },
+    ],
+  })
+}
+
+// printResolvedDestinations imprime, antes da gravação, o escopo escolhido e
+// os caminhos de destino que serão afetados (ADR D5) — nunca em modo --json,
+// que já é o canal determinístico consumido por scripts. Recalcula os planos
+// via buildPlans (sem side effect) só para enumerar destinos; a gravação em
+// si acontece depois, em execute().
+function printResolvedDestinations(kind, options) {
+  if (options.json) return
+  const plans = buildPlans(kind, options)
+  const destinations = [...new Set(plans.map(plan => plan.destination))].sort()
+  console.log(`Destino (${options.scope}):`)
+  for (const destination of destinations) console.log(`  ${destination}`)
+}
+
 async function promptAmbiguousSurfaces(kind, options, prompts = require('@inquirer/prompts')) {
   const { select } = prompts
   const selected = parseSurfaces(options.surfaces)
@@ -47,7 +107,7 @@ function createLifecycleCommand(kind) {
     const command = new Command(operation)
       .option('--targets <targets>', 'Comma-separated target CLIs', csv)
       .option('--items <items>', `Comma-separated ${kind} IDs`, csv)
-      .option('--scope <scope>', 'Installation scope: project or global', 'project')
+      .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')
@@ -65,7 +125,14 @@ function createLifecycleCommand(kind) {
 
     command.action(async (options, cmd) => {
       options.surfaces = options.surface || []
-      if (options.scope !== 'project' && options.scope !== 'global') throw new Error(`Unsupported scope: ${options.scope}`)
+
+      // Gate de escopo (ADR D1-D3, D6): resolvido incondicionalmente aqui,
+      // antes de qualquer seleção de targets/surfaces ou construção de
+      // planos, e independentemente de --targets já ter sido informado —
+      // caso contrário o caso mais comum (`agents install --targets claude`)
+      // nunca passaria por prompt algum. `list` (mutation === false) nunca
+      // pergunta (comando de leitura), apenas adota o default `global`.
+      options.scope = await resolveScope(options, { interactive: mutation, operation })
 
       // O booleano de --identity nunca deve chegar a execute()/buildPlans()
       // sob a chave "identity" — essa chave ali é reservada para uma Config
@@ -112,6 +179,10 @@ function createLifecycleCommand(kind) {
         }
       }
 
+      // D5: caminhos de destino impressos antes da gravação, apenas para
+      // operações de mutação (install/update/uninstall) e fora de --json.
+      if (mutation) printResolvedDestinations(kind, options)
+
       const output = execute(kind, operation, options)
       console.log(options.json ? JSON.stringify(output) : human(output))
     })
@@ -120,4 +191,4 @@ function createLifecycleCommand(kind) {
   return root
 }
 
-module.exports = { createLifecycleCommand, csv, human, promptSelection, promptAmbiguousSurfaces }
+module.exports = { createLifecycleCommand, csv, human, promptSelection, promptAmbiguousSurfaces, resolveScope }

package/src/commands/log.js

@@ -3,13 +3,14 @@ const { Command } = require('commander')
 const fs = require('fs')
 const path = require('path')
 const { t } = require('../i18n')
+const config = require('../config')
 
 const cmd = new Command('log')
 cmd.description(t('log.description'))
 cmd.option('--tail <n>', t('log.tail'), '20')
 cmd.action(async (opts) => {
   const tail = parseInt(opts.tail, 10)
-  const logPath = path.join('docs', 'roadmaps', '.trackfw-log')
+  const logPath = path.join(config.load().roadmapDir, '.trackfw-log')
 
   if (!fs.existsSync(logPath)) {
     console.log(t('log.empty'))

package/src/commands/note.js

@@ -0,0 +1,24 @@
+'use strict'
+
+const { Command } = require('commander')
+const { newNote } = require('../generators/note')
+
+function createNoteCommand() {
+  const note = new Command('note').description('Manage vault knowledge notes')
+
+  note
+    .command('new <title>')
+    .description('Create a new knowledge note in vault/notes/')
+    .action((title) => {
+      try {
+        newNote(title)
+      } catch (err) {
+        console.error(`error: ${err.message}`)
+        process.exit(1)
+      }
+    })
+
+  return note
+}
+
+module.exports = createNoteCommand()

package/src/commands/req.js

@@ -1,6 +1,6 @@
 'use strict'
 const { Command } = require('commander')
-const { listREQs } = require('../generators/req')
+const { listREQs, moveREQ } = require('../generators/req')
 const { t } = require('../i18n')
 
 const cmd = new Command('req')
@@ -67,4 +67,10 @@ cmd.command('list')
     listREQs(require('../config').load().reqDir)
   })
 
+cmd.command('move <name> <status>')
+  .description('Update a REQ status in place')
+  .action(async (name, status) => {
+    moveREQ(name, status)
+  })
+
 module.exports = cmd

package/src/commands/roadmap.js

@@ -8,15 +8,16 @@ cmd.description(t('roadmap.description'))
 
 cmd.command('new')
   .description(t('roadmap.new.description'))
-  .option('-t, --title <title>', 'Roadmap title')
+  .argument('[title]', 'Roadmap title')
+  .option('-t, --title <title>', 'Roadmap title (alias)')
   .option('-r, --req <path>', 'Path to the linked REQ')
   .option('--from-req <path>', 'Generate roadmap with ML stubs from REQ acceptance criteria')
-  .action(async (opts) => {
+  .action(async (titleArg, opts) => {
     if (opts.fromReq) {
       newRoadmapFromReq(opts.fromReq)
       return
     }
-    const title = opts.title || 'New Roadmap'
+    const title = titleArg || opts.title || 'New Roadmap'
     const reqPath = opts.req || ''
     newRoadmap(title, reqPath)
   })

package/src/commands/ship.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const { Command } = require('commander')
+const { runShip } = require('../ship/runner')
+const config = require('../config')
+
+function createShipCommand() {
+  const cmd = new Command('ship')
+  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' +
+      '  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' +
+      '  6. Pushes to origin (adds -u if no upstream is configured yet)\n' +
+      '  7. Opens PR/MR via the resolved forge CLI (or prints URL if CLI is absent)\n\n' +
+      "Stage your files explicitly before running ship.\n" +
+      "This command never executes 'git add .' or 'git add -A'."
+    )
+    .option('-m, --message <msg>', 'Commit message (Conventional Commits format required)')
+    .option('--dry-run', 'Print what would be done without executing write commands', false)
+    .option('--no-pr', 'Skip PR/MR creation after push')
+    .option('--forge <forge>', 'Override forge detection (github, gitlab, bitbucket, azure)', '')
+    .action((options) => {
+      const cfg = config.load()
+      const exitCode = runShip(
+        {
+          message: options.message || '',
+          dryRun: options.dryRun || false,
+          noPR: options.pr === false,
+          forge: options.forge || '',
+        },
+        {
+          configForge: cfg.forge || '',
+          repoDir: '.',
+        }
+      )
+      if (exitCode !== 0) {
+        process.exit(exitCode)
+      }
+    })
+
+  return cmd
+}
+
+module.exports = createShipCommand()

package/src/config/index.js

@@ -26,9 +26,11 @@ function defaults() {
     lenientUntil: '',
     wipLimit: 1,
     wipBySquad: false,
+    staleWipDays: 7,
     requireReqInCommit: false,
     strictCiPaths: false,
     traceIdField: '',
+    forge: '',
     // NOVOS campos:
     linkFields: {
       req:     ['REQ:'],
@@ -42,7 +44,7 @@ function defaults() {
       wip_limit:            'error',
       stale_wip:            'warning',
       adr_orphan:           'warning',
-      ref_targets_exist:    'warning',
+      ref_targets_exist:    'error',
       folder_status:        'warning',
       filename_uniqueness:  'error',
       blocked_by_draft_adr: 'error',
@@ -191,9 +193,11 @@ function parse(content, cfg) {
       case 'lenient_until':         cfg.lenientUntil = val; break;
       case 'wip_limit':             { const n = parseInt(val, 10); if (n > 0) cfg.wipLimit = n; break; }
       case 'wip_by_squad':          cfg.wipBySquad = val === 'true'; break;
+      case 'stale_wip_days':        { const n = parseInt(val, 10); if (n > 0) cfg.staleWipDays = n; break; }
       case 'require_req_in_commit': cfg.requireReqInCommit = val === 'true'; break;
       case 'strict_ci_paths':       cfg.strictCiPaths = val === 'true'; break;
       case 'trace_id_field':        cfg.traceIdField = val.replace(/^["']|["']$/g, ''); break;
+      case 'forge':                 cfg.forge = val.replace(/^["']|["']$/g, ''); break;
       case 'link_fields':           inLinkFields = true; break;
       case 'acceptance_markers':    inAcceptanceMarkers = true; acceptanceMarkers = []; break;
       case 'rules':                 inRules = true; rules = {}; break;
@@ -208,4 +212,3 @@ const NAMESPACING_FLAT = 'flat';
 const NAMESPACING_BY_AGENT = 'by_agent';
 
 module.exports = { load, reset, defaults, expandPath, NAMESPACING_FLAT, NAMESPACING_BY_AGENT };
-