trackfw 3.0.0 → 3.1.0

package/src/forge/resolve.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * forge/resolve.js — Forge resolution for trackfw ship.
+ *
+ * Precedence (highest → lowest):
+ *  1. --forge flag (explicit override)
+ *  2. forge: field in trackfw.yaml
+ *  3. Host extracted from git remote get-url origin
+ *  4. CI configuration files in repo root (.gitlab-ci.yml / .github/workflows/)
+ *  5. "manual" — never an error
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/** Accepted values for the --forge flag and forge: config field. */
+const VALID_FORGES = ['github', 'gitlab', 'bitbucket', 'azure'];
+
+/**
+ * Resolve the forge from the given inputs.
+ *
+ * @param {object} input
+ * @param {string} [input.flagForge]   - value from --forge flag
+ * @param {string} [input.configForge] - value from trackfw.yaml forge: field
+ * @param {string} [input.remoteURL]   - output of "git remote get-url origin"
+ * @param {string} [input.repoDir]     - repo root for CI file detection
+ * @returns {{ forge: string, source: string }} Resolution object.
+ *   forge ∈ {"github", "gitlab", "bitbucket", "azure", "manual"}
+ *   source ∈ {"flag", "config", "remote", "ci", "none"}
+ * @throws {Error} if flagForge or configForge contains an invalid value.
+ */
+function resolve(input) {
+  const { flagForge = '', configForge = '', remoteURL = '', repoDir = '' } = input || {};
+
+  // 1. Explicit flag wins everything.
+  if (flagForge) {
+    validateForge(flagForge);
+    return { forge: flagForge, source: 'flag' };
+  }
+
+  // 2. Config field.
+  if (configForge) {
+    validateForge(configForge);
+    return { forge: configForge, source: 'config' };
+  }
+
+  // 3. Remote URL — known hosts only.
+  if (remoteURL) {
+    const forge = forgeFromRemoteURL(remoteURL);
+    if (forge) return { forge, source: 'remote' };
+  }
+
+  // 4. CI files — desempate for self-hosted / unknown host.
+  if (repoDir) {
+    const forge = forgeFromCI(repoDir);
+    if (forge) return { forge, source: 'ci' };
+  }
+
+  // 5. Manual — not an error.
+  return { forge: 'manual', source: 'none' };
+}
+
+/**
+ * Production entry point: runs "git remote get-url origin" in repoDir,
+ * then calls resolve().
+ */
+function resolveFromRepo(flagForge, configForge, repoDir) {
+  const remoteURL = gitRemoteURL(repoDir);
+  return resolve({ flagForge, configForge, remoteURL, repoDir });
+}
+
+/** @throws {Error} if forge is not in VALID_FORGES */
+function validateForge(forge) {
+  if (!VALID_FORGES.includes(forge)) {
+    throw new Error(
+      `invalid forge "${forge}": accepted values are ${VALID_FORGES.join(', ')}`
+    );
+  }
+}
+
+function forgeFromRemoteURL(rawURL) {
+  const host = extractHost(rawURL);
+  return hostToForge(host);
+}
+
+/**
+ * Extracts the lowercase hostname from HTTPS, SSH (git@) or ssh:// URLs.
+ */
+function extractHost(rawURL) {
+  if (!rawURL) return '';
+  rawURL = rawURL.trim();
+
+  // SSH short form: git@github.com:org/repo.git
+  if (rawURL.startsWith('git@')) {
+    const rest = rawURL.slice(4); // strip "git@"
+    const colonIdx = rest.indexOf(':');
+    if (colonIdx >= 0) return rest.slice(0, colonIdx).toLowerCase();
+    return '';
+  }
+
+  // SSH long form: ssh://git@github.com/org/repo.git
+  if (rawURL.startsWith('ssh://')) {
+    let rest = rawURL.slice(6); // strip "ssh://"
+    const atIdx = rest.indexOf('@');
+    if (atIdx >= 0) rest = rest.slice(atIdx + 1); // strip user@
+    const slashIdx = rest.indexOf('/');
+    return slashIdx >= 0
+      ? rest.slice(0, slashIdx).toLowerCase()
+      : rest.toLowerCase();
+  }
+
+  // HTTPS / HTTP
+  if (rawURL.startsWith('https://') || rawURL.startsWith('http://')) {
+    let rest = rawURL.replace(/^https?:\/\//, '');
+    // strip optional user:pass@
+    const atIdx = rest.indexOf('@');
+    if (atIdx >= 0) rest = rest.slice(atIdx + 1);
+    const slashIdx = rest.indexOf('/');
+    return slashIdx >= 0
+      ? rest.slice(0, slashIdx).toLowerCase()
+      : rest.toLowerCase();
+  }
+
+  return '';
+}
+
+/**
+ * Maps a known hostname to its forge identifier.
+ * Azure DevOps uses dev.azure.com (HTTPS) and ssh.dev.azure.com (SSH).
+ * Returns '' for unknown / self-hosted hosts.
+ */
+function hostToForge(host) {
+  if (!host) return '';
+  if (host === 'github.com') return 'github';
+  if (host === 'gitlab.com') return 'gitlab';
+  if (host === 'bitbucket.org') return 'bitbucket';
+  if (
+    host === 'dev.azure.com' ||
+    host.endsWith('.dev.azure.com') ||
+    host.endsWith('.visualstudio.com')
+  ) {
+    return 'azure';
+  }
+  return '';
+}
+
+/**
+ * Inspects CI indicator files in repoDir.
+ * Priority: .gitlab-ci.yml → gitlab; .github/workflows/ → github.
+ */
+function forgeFromCI(repoDir) {
+  try {
+    fs.statSync(path.join(repoDir, '.gitlab-ci.yml'));
+    return 'gitlab';
+  } catch (_) {}
+
+  try {
+    const stat = fs.statSync(path.join(repoDir, '.github', 'workflows'));
+    if (stat.isDirectory()) return 'github';
+  } catch (_) {}
+
+  return '';
+}
+
+/**
+ * Runs "git remote get-url origin" in repoDir.
+ * Returns '' on any error.
+ */
+function gitRemoteURL(repoDir) {
+  try {
+    return execSync('git remote get-url origin', {
+      cwd: repoDir,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    }).trim();
+  } catch (_) {
+    return '';
+  }
+}
+
+module.exports = {
+  VALID_FORGES,
+  resolve,
+  resolveFromRepo,
+  validateForge,
+  extractHost,
+  hostToForge,
+  forgeFromCI,
+};

package/src/generators/adr.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs')
 const path = require('path')
+const { localDateISO } = require('./date')
 
 /**
  * Converte uma string em slug: lowercase + espaços → hifens.
@@ -9,7 +10,13 @@ const path = require('path')
  * @returns {string}
  */
 function toSlug(s) {
-  return s.toLowerCase().replace(/ /g, '-')
+  // NFKD normalization + remove combining marks (diacríticos) + lowercase + non-alphanumeric → hífen
+  return s
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
 }
 
 /**
@@ -26,11 +33,13 @@ function slugToTitle(slug) {
 }
 
 /**
- * Retorna a data atual no formato YYYY-MM-DD.
+ * Retorna a data LOCAL atual no formato YYYY-MM-DD.
+ * Delega para localDateISO() — usa getDate/getMonth/getFullYear (hora local),
+ * não toISOString (UTC).
  * @returns {string}
  */
 function today() {
-  return new Date().toISOString().slice(0, 10)
+  return localDateISO()
 }
 
 /**
@@ -182,4 +191,4 @@ author: ""
   return filename
 }
 
-module.exports = { newADR, listADRs, newADRDraft, toSlug }
+module.exports = { newADR, listADRs, newADRDraft, toSlug, today }

package/src/generators/date.js

@@ -0,0 +1,23 @@
+'use strict'
+
+/**
+ * localDateISO — retorna a data LOCAL atual no formato YYYY-MM-DD.
+ *
+ * Usa getFullYear/getMonth/getDate (métodos de hora local) em vez de
+ * toISOString() (que retorna sempre UTC). Isso garante que uma REQ criada às
+ * 22h no Brasil seja datada do dia correto, independentemente do fuso da
+ * máquina — comportamento idêntico ao de Go (time.Now().Format("2006-01-02"))
+ * e Python (date.today().isoformat()).
+ *
+ * @returns {string} Data no formato "YYYY-MM-DD"
+ */
+function localDateISO() {
+  const d = new Date()
+  return [
+    d.getFullYear(),
+    String(d.getMonth() + 1).padStart(2, '0'),
+    String(d.getDate()).padStart(2, '0'),
+  ].join('-')
+}
+
+module.exports = { localDateISO }

package/src/generators/init.js

@@ -13,6 +13,7 @@ const GOV_DIRS = [
   'docs/roadmaps/blocked',
   'docs/roadmaps/done',
   'docs/roadmaps/abandoned',
+  'vault/notes',
 ]
 
 const GLOBAL_ADRS_DIRECTIVE = 'Obrigatório: Inspecione e respeite todos os ADRs globais nos diretórios listados em adr_dirs (inclusive caminhos ~/...) antes de propor alterações de arquitetura.'
@@ -28,6 +29,7 @@ async function scaffold(cfg, cwd) {
     console.log(`  ✓ ${dir}`)
   }
 
+  generateVaultIndex(root)
   writeTrackfwConfig(cfg, root)
   generateValidateScript(cfg, root)
   generateAttentionScripts(cfg, root)
@@ -40,6 +42,29 @@ async function scaffold(cfg, cwd) {
   injectHooksDetected(root)
 }
 
+/**
+ * generateVaultIndex — cria vault/notes/index.md se ainda não existir.
+ * @param {string} root
+ */
+function generateVaultIndex(root) {
+  const indexPath = path.join(root || process.cwd(), 'vault', 'notes', 'index.md')
+  if (fs.existsSync(indexPath)) return
+  const content = `# Vault de Conhecimento
+
+> Ponto de entrada de conhecimento do projeto para agentes e pessoas.
+> Cada nota documenta uma causa-raiz, decisão técnica ou restrição não óbvia.
+> Crie notas com: trackfw note new "<título>"
+
+## Índice
+
+<!-- As notas serão listadas abaixo. Exemplo:
+- [nome-da-nota-YYYY-MM-DD](nome-da-nota-YYYY-MM-DD.md)
+-->
+`
+  fs.writeFileSync(indexPath, content, 'utf8')
+  console.log('  ✓ vault/notes/index.md')
+}
+
 // ---------------------------------------------------------------------------
 // trackfw.yaml
 // ---------------------------------------------------------------------------
@@ -54,7 +79,7 @@ backend: ${cfg.backend || ''}
 backend_framework: ${cfg.backendFramework || ''}
 pkg_manager: ${cfg.pkgManager || ''}
 hooks: ${cfg.hooks || ''}
-ci: ${cfg.ci || ''}
+ci: ${cfg.ci || ''}${cfg.forge ? `\nforge: ${cfg.forge}` : ''}
 require_req_in_commit: ${cfg.requireReqInCommit ? 'true' : 'false'}
 
 # governance paths (edit to match your project structure)
@@ -585,6 +610,66 @@ function generateClaudeMD(cfg) {
       content += 'No CI gate configured.\n'
   }
 
+  // Harness sections — derived from project governance conventions
+  content += '\n## Branch strategy\n\n'
+  content += 'One active branch at a time. Name it `feat/<slug>`, `fix/<slug>` or `refactor/<slug>`. '
+  content += 'Before creating a new branch, verify no other is genuinely open: run `git fetch origin --prune`, '
+  content += 'then `git branch -r --no-merged origin/main`, then for each candidate `git diff origin/main <branch> --stat`. '
+  content += 'An empty diff means it was squash-merged — ignore it. '
+  content += 'Squash merges do not mark a branch as merged, so `--no-merged` alone is not evidence. '
+  content += 'If the branch is stale and the diff looks inflated by main\'s own evolution, '
+  content += 'compare only the files the branch itself touched since the merge base.\n\n'
+
+  content += '## Definition of done\n\n'
+  content += 'Green build and tests do not close a microbatch. '
+  content += 'It is done when the requirement and the roadmap sit in the correct state folder, '
+  content += 'their declared status matches that folder, the final validation is recorded with evidence, '
+  content += 'no duplicate copy remains in another state, and `trackfw validate` reports no violations.\n\n'
+
+  content += '## Requirement scope\n\n'
+  content += 'Every requirement must declare an explicit negative scope: what must not be implemented. '
+  content += 'Boundaries prevent an implementing agent from inventing work.\n\n'
+
+  content += '## State requirements\n\n'
+  content += '`blocked` requires a reason and an owner. '
+  content += '`abandoned` requires a reason and a successor. '
+  content += '`wip` must reflect work that is genuinely active; '
+  content += 'anything stalled moves to `blocked` or `abandoned` instead of rotting in `wip`.\n\n'
+
+  content += '## Roadmap format\n\n'
+  content += 'Organize work as waves of microbatches. '
+  content += 'A wave groups microbatches that can run in parallel; a barrier separates waves. '
+  content += 'Microbatches sharing any file — including generated trees and build outputs — must be sequential, '
+  content += 'and the reason is documented. '
+  content += 'Each microbatch declares exact files, exact actions, measurable acceptance criteria and exact validation commands, '
+  content += 'so that a small model can execute it without guessing.\n\n'
+
+  content += '## When governance is not required\n\n'
+  content += 'A closed list of exemptions: a typo or local variable rename; a documentation-only change; '
+  content += 'a configuration tweak with no runtime effect; a direct revert; '
+  content += 'answering a question or reviewing without changes. '
+  content += 'Additionally, when the user reports a concrete bug, fix it directly and do not open an architectural analysis for it. '
+  content += '**This section takes precedence over the general rule that requires a requirement and a roadmap.** '
+  content += 'Anything touching business logic, an API contract, a data schema, authentication or authorization, '
+  content += 'localization, or user-facing behavior always requires governance, regardless of how few files it touches.\n\n'
+
+  content += '## Production incidents\n\n'
+  content += 'Inspect the live environment before proposing a fix: real variables, active credentials, '
+  content += 'granted permissions, running processes. '
+  content += 'Confirm the root cause against real evidence, then implement the smallest fix. '
+  content += 'Never edit static configuration files as a response to a root cause that has not been confirmed in the running environment.\n\n'
+
+  content += '## Iterative prototyping\n\n'
+  content += 'For complex or uncertain user-facing work, validate the concept with a disposable, isolated prototype '
+  content += 'that the user reviews visually, and only then write the decision record and the production roadmap. '
+  content += 'Build and test success is not evidence that an interface is right.\n\n'
+
+  content += '## Autopilot\n\n'
+  content += 'Ask everything you need before starting. '
+  content += 'Once started, do not interrupt for confirmations that could have been anticipated. '
+  content += 'Decide low-risk details autonomously following existing project conventions, '
+  content += 'and record autonomous decisions in the commit message.\n'
+
   injectOrUpdateRules('CLAUDE.md', content)
   console.log('  ✓ CLAUDE.md')
 }
@@ -700,9 +785,16 @@ trackfw não está instalado. Instale com:
    Com base no conteúdo da REQ, gere um roadmap seguindo **estritamente** este formato:
 
    \`\`\`markdown
+   ---
+   status: backlog
+   date: <YYYY-MM-DD>
+   req: "docs/req/<arquivo-selecionado>.md"
+   squad: ""
+   ---
+
    # Roadmap: <título derivado da REQ>
 
-   > Criado em: <YYYY-MM-DD> | Status: ⬜ Backlog
+   > Created: <YYYY-MM-DD> | Status: backlog
 
    ## Diagnóstico / Contexto
    <resumo do problema, motivação e escopo extraídos da REQ>
@@ -720,6 +812,13 @@ trackfw não está instalado. Instale com:
    - [ ] build sem erros
    - [ ] testes verdes
    **Comandos de validação:** \`<comando de build e teste do projeto>\`
+
+   ### ML-1B — <título> (se independente de ML-1A)
+   ...
+
+   ## Wave 2 — <nome> (depende de Wave 1)
+   > Dependências: Wave 1 completa
+   ...
    \`\`\`
 
    **Princípios obrigatórios:**
@@ -732,10 +831,12 @@ trackfw não está instalado. Instale com:
 4. **Salvar o arquivo**
    - Calcule o slug: título em lowercase, espaços → hifens, remova caracteres especiais
    - Crie o arquivo em \`docs/roadmaps/backlog/ROADMAP-<YYYY-MM-DD>-<slug>.md\`
+   - Preencha \`req:\` com o caminho relativo completo da REQ selecionada
    - Use a data de hoje
 
 5. **Confirmar**
-   Informe o caminho do arquivo criado e um resumo das Waves e total de MLs gerados.`,
+   Informe o caminho do arquivo criado e um resumo das Waves e total de MLs gerados.
+`,
 
     'implement.md': `Você é o orquestrador de implementação do trackfw. Siga o fluxo abaixo **sem pular etapas**.
 
@@ -1139,6 +1240,7 @@ module.exports = {
   generateClaudeMD,
   generateClaudeCommands,
   generateClaudeCommandsForce,
+  generateVaultIndex,
   installSkillsForce,
   installAgents,
   installGemini,

package/src/generators/note.js

@@ -0,0 +1,154 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { localDateISO } = require('./date')
+
+const VAULT_DIR = 'vault/notes'
+const INDEX_FILE = 'vault/notes/index.md'
+
+/**
+ * Converte título em slug kebab-case lowercase sem acentos.
+ * Reutiliza a mesma lógica do adr.js (toSlug).
+ * @param {string} s
+ * @returns {string}
+ */
+function toSlug(s) {
+  // NFKD normalization + remove combining marks (diacríticos) + lowercase + non-alphanumeric → hífen
+  return s
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/**
+ * Retorna a data LOCAL atual no formato YYYY-MM-DD.
+ * Delega para localDateISO() — usa getDate/getMonth/getFullYear (hora local),
+ * não toISOString (UTC).
+ * @returns {string}
+ */
+function today() {
+  return localDateISO()
+}
+
+/**
+ * Cria uma nova nota em vault/notes/<slug>-YYYY-MM-DD.md e linka no index.md.
+ * Idempotente: falha com erro claro se a nota já existir.
+ * @param {string} title
+ * @param {string} [cwd]
+ */
+function newNote(title, cwd) {
+  const root = cwd || process.cwd()
+  const vaultDir = path.join(root, VAULT_DIR)
+  fs.mkdirSync(vaultDir, { recursive: true })
+
+  const slug = toSlug(title)
+  const date = today()
+  const filename = `${slug}-${date}.md`
+  const notePath = path.join(vaultDir, filename)
+
+  if (fs.existsSync(notePath)) {
+    throw new Error(`nota "${filename}" já existe — não sobrescrita`)
+  }
+
+  const body = `---
+title: "${title}"
+tags: []
+date: ${date}
+related: []
+---
+
+# ${title}
+
+## Problem
+
+<!-- Descreva o problema ou situação que motivou esta nota. -->
+
+## Root cause
+
+<!-- Qual foi a causa raiz identificada? -->
+
+## Solution
+
+<!-- Como foi resolvido ou mitigado? O que deve ser feito? -->
+`
+
+  fs.writeFileSync(notePath, body, 'utf8')
+  appendNoteToIndex(filename, root)
+  console.log(`created ${path.join(VAULT_DIR, filename)}`)
+}
+
+/**
+ * Acrescenta link para filename no vault/notes/index.md.
+ * Cria o index.md se não existir. Não duplica se já estiver linkado.
+ * @param {string} filename
+ * @param {string} [cwd]
+ */
+function appendNoteToIndex(filename, cwd) {
+  const root = cwd || process.cwd()
+  const indexPath = path.join(root, INDEX_FILE)
+
+  if (!fs.existsSync(indexPath)) {
+    const initial = `# Vault de Conhecimento
+
+> Ponto de entrada de conhecimento do projeto para agentes e pessoas.
+
+## Índice
+
+`
+    fs.writeFileSync(indexPath, initial, 'utf8')
+  }
+
+  const content = fs.readFileSync(indexPath, 'utf8')
+  const nameWithoutExt = filename.replace(/\.md$/, '')
+
+  // Verifica se já linkado (link markdown ou wikilink)
+  if (
+    content.includes(`(${filename})`) ||
+    content.includes(`[[${nameWithoutExt}]]`) ||
+    content.includes(`[[${filename}]]`)
+  ) {
+    return
+  }
+
+  const link = `- [${nameWithoutExt}](${filename})\n`
+  fs.appendFileSync(indexPath, link, 'utf8')
+}
+
+/**
+ * Retorna todos os arquivos .md em vault/notes/ exceto index.md.
+ * Retorna [] se o diretório não existir.
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+function noteFiles(cwd) {
+  const root = cwd || process.cwd()
+  const vaultDir = path.join(root, VAULT_DIR)
+  if (!fs.existsSync(vaultDir)) return []
+  return fs
+    .readdirSync(vaultDir)
+    .filter((f) => f.endsWith('.md') && f !== 'index.md')
+}
+
+/**
+ * Retorna true se o index.md referencia filename.
+ * @param {string} filename
+ * @param {string} [cwd]
+ * @returns {boolean}
+ */
+function indexContains(filename, cwd) {
+  const root = cwd || process.cwd()
+  const indexPath = path.join(root, INDEX_FILE)
+  if (!fs.existsSync(indexPath)) return false
+  const content = fs.readFileSync(indexPath, 'utf8')
+  const nameWithoutExt = filename.replace(/\.md$/, '')
+  return (
+    content.includes(`(${filename})`) ||
+    content.includes(`[[${nameWithoutExt}]]`) ||
+    content.includes(`[[${filename}]]`)
+  )
+}
+
+module.exports = { newNote, appendNoteToIndex, noteFiles, indexContains, toSlug, today }