trackfw 3.0.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 |
@@ -372,14 +377,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": "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

@@ -10,6 +10,7 @@ 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')
@@ -29,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
@@ -45,6 +54,7 @@ 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)
@@ -62,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, scope
+  // 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({
@@ -163,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')
@@ -202,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')}`)
@@ -229,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())
@@ -236,7 +274,7 @@ 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(), scope)

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 };
-

package/src/forge/adapter.js

@@ -0,0 +1,189 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Verificação de disponibilidade de CLI — scan puro no PATH sem subprocess
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica se um executável está disponível no PATH, respeitando
+ * TRACKFW_DISABLE_EXTERNAL_COMMANDS (mesmo padrão de discover.go).
+ * @param {string} name
+ * @returns {boolean}
+ */
+function _defaultAvailFn(name) {
+  if (!name) return false;
+  if (process.env.TRACKFW_DISABLE_EXTERNAL_COMMANDS === '1') return false;
+
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const isWindows = process.platform === 'win32';
+  const exts = isWindows
+    ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
+    : [''];
+
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      try {
+        const candidate = path.join(dir, name + ext);
+        fs.accessSync(candidate, fs.constants.F_OK | fs.constants.X_OK);
+        return true;
+      } catch (_) {
+        // continua
+      }
+    }
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Conversão de remote URL → base HTTPS
+// ---------------------------------------------------------------------------
+
+/**
+ * Converte qualquer formato de remote git (git@, ssh://, https://, http://)
+ * para URL base HTTPS sem .git.
+ *
+ * Normalização especial para Azure SSH:
+ *   git@ssh.dev.azure.com:v3/org/project/repo → https://dev.azure.com/org/project/_git/repo
+ *
+ * @param {string} rawURL
+ * @param {string} forge
+ * @returns {string}
+ */
+function remoteHTTPSBase(rawURL, forge) {
+  if (!rawURL) return '';
+  rawURL = rawURL.trim();
+  if (!rawURL) return '';
+
+  let host = '';
+  let pathStr = '';
+
+  if (rawURL.startsWith('git@')) {
+    // git@host:path
+    const rest = rawURL.slice(4);
+    const colonIdx = rest.indexOf(':');
+    if (colonIdx < 0) return '';
+    host = rest.slice(0, colonIdx).toLowerCase();
+    pathStr = rest.slice(colonIdx + 1);
+
+  } else if (rawURL.startsWith('ssh://')) {
+    // ssh://[user@]host/path
+    let rest = rawURL.slice(6);
+    const atIdx = rest.indexOf('@');
+    if (atIdx >= 0) rest = rest.slice(atIdx + 1);
+    const slashIdx = rest.indexOf('/');
+    if (slashIdx < 0) {
+      host = rest.toLowerCase();
+    } else {
+      host = rest.slice(0, slashIdx).toLowerCase();
+      pathStr = rest.slice(slashIdx + 1);
+    }
+
+  } else if (rawURL.startsWith('https://') || rawURL.startsWith('http://')) {
+    let rest = rawURL.replace(/^https?:\/\//, '');
+    const atIdx = rest.indexOf('@');
+    if (atIdx >= 0) rest = rest.slice(atIdx + 1);
+    const slashIdx = rest.indexOf('/');
+    if (slashIdx < 0) {
+      host = rest.toLowerCase();
+    } else {
+      host = rest.slice(0, slashIdx).toLowerCase();
+      pathStr = rest.slice(slashIdx + 1);
+    }
+
+  } else {
+    return '';
+  }
+
+  pathStr = pathStr.replace(/\.git$/, '').replace(/^\/|\/$/g, '');
+
+  // Normalização Azure SSH
+  if (forge === 'azure' && host === 'ssh.dev.azure.com') {
+    host = 'dev.azure.com';
+    pathStr = pathStr.replace(/^v3\//, '');
+    const parts = pathStr.split('/');
+    if (parts.length === 3) {
+      pathStr = `${parts[0]}/${parts[1]}/_git/${parts[2]}`;
+    }
+  }
+
+  if (!pathStr) return `https://${host}`;
+  return `https://${host}/${pathStr}`;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} Adapter
+ * @property {string} forge
+ * @property {string} noun        - "Pull Request" ou "Merge Request"
+ * @property {string} cliName     - nome do executável (vazio = sem CLI)
+ * @property {string[]} cliArgs   - argumentos para criar PR/MR
+ * @property {boolean} available  - false quando CLI ausente
+ * @property {function(string, string): string} fallbackURL
+ */
+
+/**
+ * Retorna o Adapter para o forge informado.
+ *
+ * @param {string} forge
+ * @param {function(string): boolean} [availFn]  - injeta verificação de CLI (para testes)
+ * @returns {Adapter}
+ */
+function forgeAdapter(forge, availFn) {
+  if (typeof availFn !== 'function') {
+    availFn = _defaultAvailFn;
+  }
+
+  let noun = 'Pull Request';
+  let cliName = '';
+  let cliArgs = [];
+  let available = false;
+
+  switch (forge) {
+    case 'github':
+      cliName = 'gh';
+      cliArgs = ['pr', 'create'];
+      available = availFn('gh');
+      break;
+    case 'gitlab':
+      noun = 'Merge Request';
+      cliName = 'glab';
+      cliArgs = ['mr', 'create'];
+      available = availFn('glab');
+      break;
+    case 'azure':
+      cliName = 'az';
+      cliArgs = ['repos', 'pr', 'create'];
+      available = availFn('az');
+      break;
+    case 'bitbucket':
+      // Bitbucket não possui CLI — nunca chama availFn
+      break;
+    default:
+      // forge desconhecido: sem CLI, sem disponibilidade
+      break;
+  }
+
+  const adapter = { forge, noun, cliName, cliArgs, available };
+
+  adapter.fallbackURL = function (remoteURL, branch) {
+    const base = remoteHTTPSBase(remoteURL, forge);
+    if (!base) return '';
+    switch (forge) {
+      case 'github':    return `${base}/compare/${branch}?expand=1`;
+      case 'gitlab':    return `${base}/-/merge_requests/new?merge_request[source_branch]=${branch}`;
+      case 'bitbucket': return `${base}/pull-requests/new?source=${branch}`;
+      case 'azure':     return `${base}/pullrequestcreate?sourceRef=${branch}`;
+      default:          return '';
+    }
+  };
+
+  return adapter;
+}
+
+module.exports = { forgeAdapter, remoteHTTPSBase };