trackfw 7.2.0 → 7.4.0

package/src/generators/init.js

@@ -4,6 +4,17 @@ const fs = require('fs')
 const path = require('path')
 const os = require('os')
 const { readAgentConventions } = require('../config/index.js')
+const { homedir } = require('../homedir');
+
+// PACKAGE_VERSION — the version of the trackfw binary generating the CI
+// workflow templates. Read once from package.json (never a literal), so
+// the pin written into the workflow always tracks the generator that
+// wrote it (ADR-2026-08-28: gate de CI nasce pinado na versão que o
+// gerou). Reused by buildGitHubActionsWorkflowContent /
+// buildGitLabCIWorkflowContent AND by scaffold doctor's comparison
+// (which calls the same functions), so drift between write and compare
+// paths is structurally impossible.
+const { version: PACKAGE_VERSION } = require('../../package.json')
 
 const GOV_DIRS = [
   'docs/adr',
@@ -31,6 +42,7 @@ async function scaffold(cfg, cwd) {
   }
 
   generateVaultIndex(root)
+  generateGitAttributes(root)
   writeTrackfwConfig(cfg, root)
   generateValidateScript(cfg, root)
   generateAttentionScripts(cfg, root)
@@ -45,6 +57,60 @@ async function scaffold(cfg, cwd) {
   injectHooksDetected(root)
 }
 
+// gitAttributesRuleTarget — primeiro campo da regra mantida por este gerador.
+// Casa o BASENAME (padrão sem barra) de propósito: `roadmap_dir` e `req_dir` são
+// configuráveis por projeto (trackfw.yaml) e ambos carregam um `.trackfw-log`,
+// então caminho fixo nasceria quebrado em quem configurou diretório diferente.
+const GITATTRIBUTES_RULE_TARGET = '.trackfw-log'
+
+// GITATTRIBUTES_BLOCK — byte-idêntico ao de internal/generators/scaffold.go e
+// pypi/trackfw/generators/init_gen.py (regra dura de paridade).
+const GITATTRIBUTES_BLOCK = `# trackfw: .trackfw-log is append-only — every write lands on the last line, so
+# two parallel branches conflict on every merge. merge=union keeps the lines
+# from both sides (chronological order is not guaranteed). The pattern has no
+# slash, so it matches the file in any directory — roadmap_dir and req_dir both
+# carry one, and both are configurable per project.
+.trackfw-log merge=union
+`
+
+/**
+ * hasGitAttributesRule — verdadeiro quando ALGUMA linha não-comentário tem
+ * `.trackfw-log` como primeiro campo. Predicado sobre o CAMPO, não sobre a
+ * string literal da linha inteira: espaçamento diferente ou outro atributo já
+ * são "a regra existe", e reescrever por cima sobrescreveria decisão do projeto.
+ * @param {string} content
+ */
+function hasGitAttributesRule(content) {
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) continue
+    if (trimmed.split(/\s+/)[0] === GITATTRIBUTES_RULE_TARGET) return true
+  }
+  return false
+}
+
+/**
+ * generateGitAttributes — garante `merge=union` para o `.trackfw-log` no
+ * `.gitattributes` da raiz. Três ramos, todos idempotentes: ausente → cria;
+ * existe sem a regra → APPEND (nunca sobrescreve); existe com a regra → no-op.
+ * @param {string} root
+ */
+function generateGitAttributes(root) {
+  const filePath = path.join(root || process.cwd(), '.gitattributes')
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, GITATTRIBUTES_BLOCK, 'utf8')
+    console.log('  ✓ .gitattributes')
+    return
+  }
+  const existing = fs.readFileSync(filePath, 'utf8')
+  if (hasGitAttributesRule(existing)) return
+  // Arquivo preexistente sem newline final: emendar direto grudaria a primeira
+  // linha do bloco na última linha do projeto, corrompendo a config em silêncio.
+  const prefix = existing !== '' && !existing.endsWith('\n') ? existing + '\n' : existing
+  fs.writeFileSync(filePath, prefix + GITATTRIBUTES_BLOCK, 'utf8')
+  console.log('  ✓ .gitattributes')
+}
+
 /**
  * generateVaultIndex — cria vault/notes/index.md se ainda não existir.
  * @param {string} root
@@ -123,6 +189,10 @@ function generateValidateScript(cfg, cwd) {
   const script = buildValidateScript(cfg)
   const scriptPath = path.join(root, 'scripts', 'trackfw-validate.sh')
   fs.writeFileSync(scriptPath, script, { encoding: 'utf8', mode: 0o755 })
+  // AC9 (REQ-2026-08-28): writeFileSync's {mode} option applies only on O_CREAT;
+  // for an existing file the mode is not changed. fs.chmodSync restores 0o755
+  // unconditionally, matching Python's os.chmod behavior (which was already correct).
+  fs.chmodSync(scriptPath, 0o755)
   console.log(`  ✓ ${path.join('scripts', 'trackfw-validate.sh')}`)
 }
 
@@ -201,17 +271,34 @@ function generateCIWorkflow(cfg) {
   }
 }
 
-function generateGitHubActionsWorkflow() {
-  fs.mkdirSync('.github/workflows', { recursive: true })
-
-  const content = `name: trackfw-gate
+// buildGitHubActionsWorkflowContent returns the byte-identical content the GitHub Actions
+// workflow generator would write. Exported for scaffold doctor (ADR-2026-08-27): the
+// comparison uses the same function the write path uses, so drift is structurally impossible.
+// The cfg parameter is accepted for API symmetry with Go's buildGitHubActionsWorkflowContent
+// (which also ignores cfg for now — the template is cfg-independent but, since
+// ADR-2026-08-28, NOT version-independent: it pins TRACKFW_VERSION to the version of the
+// trackfw binary that generated it, read from package.json — never a literal).
+//
+// Job id is `governance-install-script` (ML-1A, ROADMAP-2026-09-01): was `governance`,
+// colliding with the discover-installed sibling workflow's job id (trackfw-validate.yml,
+// buildDiscoverGitHubActionsWorkflowContent in commands/discover.js) — both previously
+// `governance`, producing two identically-named check-runs on any PR of a project with
+// both workflows installed, which makes required_status_checks ambiguous (GitHub
+// matches by name). Named after the install mechanism (install.sh here, `go install`
+// there) rather than the workflow file, since that's what a required_status_checks
+// reader needs to tell the two apart without opening the YAML.
+function buildGitHubActionsWorkflowContent(_cfg) {
+  return `name: trackfw-gate
 on:
   pull_request:
     branches: [main]
 
 jobs:
-  governance:
+  governance-install-script:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      TRACKFW_VERSION: "${PACKAGE_VERSION}"
     steps:
       - uses: actions/checkout@v4
 
@@ -222,17 +309,18 @@ jobs:
       - name: Governance gate
         run: trackfw validate
 `
-
-  const filePath = '.github/workflows/trackfw-gate.yml'
-  fs.writeFileSync(filePath, content, 'utf8')
-  console.log(`  ✓ ${filePath}`)
 }
 
-function generateGitLabCIWorkflow() {
-  const content = `# trackfw governance gate
+// buildGitLabCIWorkflowContent mirrors buildGitHubActionsWorkflowContent for GitLab CI.
+// Same version-pin rationale as above — see buildGitHubActionsWorkflowContent.
+function buildGitLabCIWorkflowContent(_cfg) {
+  return `# trackfw governance gate
 trackfw-gate:
   stage: test
   image: alpine:latest
+  timeout: 10 minutes
+  variables:
+    TRACKFW_VERSION: "${PACKAGE_VERSION}"
   before_script:
     - apk add --no-cache curl
     - curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
@@ -241,8 +329,17 @@ trackfw-gate:
   only:
     - merge_requests
 `
+}
+
+function generateGitHubActionsWorkflow() {
+  fs.mkdirSync('.github/workflows', { recursive: true })
+  const filePath = '.github/workflows/trackfw-gate.yml'
+  fs.writeFileSync(filePath, buildGitHubActionsWorkflowContent(null), 'utf8')
+  console.log(`  ✓ ${filePath}`)
+}
 
-  fs.writeFileSync('.gitlab-ci-trackfw.yml', content, 'utf8')
+function generateGitLabCIWorkflow() {
+  fs.writeFileSync('.gitlab-ci-trackfw.yml', buildGitLabCIWorkflowContent(null), 'utf8')
   console.log('  ✓ .gitlab-ci-trackfw.yml')
 }
 
@@ -320,9 +417,12 @@ function generateCommitMsgHook(cfg) {
 // ---------------------------------------------------------------------------
 
 function generatePomXml(cfg) {
-  const slug = cfg.projectName
-    ? cfg.projectName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '')
-    : 'my-app'
+  // Usa o toSlug compartilhado em vez de uma variante inline: a versao anterior nao
+  // fazia NFKD e PERDIA a letra acentuada — "Cafe App" (com acento) virava "caf-app"
+  // aqui e "cafe-app" no Go, que usa o toSlug dele. Ver a secao
+  // "Artifact slug contract" em docs/cli-parity.md.
+  const { toSlug } = require('./adr')
+  const slug = cfg.projectName ? toSlug(cfg.projectName) : 'my-app'
   const name = cfg.projectName || 'My App'
   const content = `<?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
@@ -452,7 +552,7 @@ Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
 - **Docker + .env from day 1:** containerize early; all config via env vars
 - **2-layer validation:** frontend (UX) + backend (security) — never only one
 - **API-first:** define OpenAPI contract before coding frontend/backend integration
-- **Security wave:** include a red-team review wave in every feature roadmap
+- **Threat model waves:** every feature roadmap opens with a Wave 0 threat model (before implementation) and closes with a red-team review wave (before release)
 - **Test coverage:** TDD for critical logic; min 60% (prototype) / 80% (production)
 - Use \`/trackfw:architect\` to define stack before the first REQ
 ` + conventionsSection + `
@@ -776,6 +876,13 @@ function backendCommands(cfg) {
 // (missing roadmap.md, implement.md, barrier.md) undetected.
 // ---------------------------------------------------------------------------
 
+// CLAUDE_COMMANDS "trackfw não está instalado" blurbs (AC13) are deliberately
+// OUT of the version pin introduced by ADR-2026-08-28. This text is shown when
+// the `trackfw` command fails because it is not installed — recommending the
+// exact old version that generated the project would be worse UX than
+// pointing at `releases/latest`, since the reason to (re)install is usually
+// being outdated. Do not pin these on a future pass without a product
+// decision; see ROADMAP-2026-08-28 Wave 0 §3 (AC13 row).
 const CLAUDE_COMMANDS = {
     'adr.md': `Execute o seguinte comando bash: \`trackfw adr new "$ARGUMENTS"\`
 
@@ -855,7 +962,7 @@ trackfw não está instalado. Instale com:
 3. **Gerar o roadmap**
    Com base no conteúdo da REQ, gere um roadmap seguindo **estritamente** este formato:
 
-   \`\`\`markdown
+   \`\`\`\`markdown
    ---
    status: backlog
    date: <YYYY-MM-DD>
@@ -870,6 +977,28 @@ trackfw não está instalado. Instale com:
    ## Diagnóstico / Contexto
    <resumo do problema, motivação e escopo extraídos da REQ>
 
+   ## Wave 0 — Threat Model
+   > Dependencies: none. Blocks all implementation.
+
+   ### ML-0A — Threat model for this roadmap
+   **Status:** pending
+   **Files affected:**
+   **Actions:**
+   1. Enumeration completeness — is the list of surfaces in this roadmap complete? Name what is missing, or show the list is closed. Do not limit the search to the files already named by the REQ — before declaring the list closed, search the repository for other places that emit the same artifact or the same pattern (for example, grep for the literal the final artifact contains).
+   2. Threat model — who empties this Wave 0 without breaking any written rule, and how?
+   3. Falsification targets in both directions — for each surface, what breaks when the behavior regresses, and what breaks when it regresses the opposite way?
+   4. Declared residual — what this design accepts not covering.
+   **Acceptance criteria:**
+   - [ ] The four sections above answered with evidence, not a one-line assertion
+   - [ ] No implementation line written for this ML
+
+   **Gates da wave:**
+   \`\`\`bash
+   # Wave 0 gate — replace this placeholder with a project-specific check before
+   # marking ML-0A done. Do not remove the gate; replace its command (AC13).
+   exit 1  # placeholder gate fails closed until ML-0A replaces it — see docs/cli-parity.md
+   \`\`\`
+
    ## Wave 1 — <nome descritivo> (<N> MLs em paralelo)
    > Dependências: Independente
 
@@ -890,7 +1019,7 @@ trackfw não está instalado. Instale com:
    ## Wave 2 — <nome> (depende de Wave 1)
    > Dependências: Wave 1 completa
    ...
-   \`\`\`
+   \`\`\`\`
 
    **Princípios obrigatórios:**
    - MLs dentro da mesma Wave são **independentes** (arquivos distintos, sem conflito)
@@ -1032,9 +1161,19 @@ Próximo passo: abrir PR com gh pr create
 
 Execute primeiro:
 \`\`\`bash
-trackfw barrier <roadmap> --wave <n> --json
+trackfw barrier <roadmap> --wave <n> --trust-local-gates --json
 \`\`\`
 
+\`--trust-local-gates\` é obrigatório aqui: roadmaps WIP (modificados localmente, ainda não commitados em
+\`origin/main\`) são marcados como não confiáveis pela CLI direta por padrão, como proteção contra a
+execução de gates de roadmaps chegados por PR de terceiro. O slash command aplica esse flag porque
+ele representa o fluxo legítimo do arquiteto operando no próprio repositório — não porque os gates
+são inspecionados previamente (o diff ainda é responsabilidade do checklist abaixo).
+
+⚠️ **Não use \`--trust-local-gates\` ao revisar um roadmap chegado por PR de terceiro** — use a CLI
+direta sem o flag (\`trackfw barrier <roadmap> --wave <n> --json\`) para que os gates sejam marcados
+como \`not_evaluated\` e não executados.
+
 Este comando é **necessário mas não suficiente**. Ele verifica MLs concluídos, evidências e \`trackfw validate\`, mas não substitui as inspeções especializadas nem a auditoria de diff abaixo — nenhuma delas é avaliada pelo binário. Consulte a seção \`trackfw barrier\` em \`docs/cli-parity.md\` para o contrato completo (estados, exit codes, saída JSON).
 
 Se o comando retornar exit code não-zero (\`blocked\` ou erro de resolução): pare, reporte a falha ao usuário e não prossiga no checklist até que a wave passe.
@@ -1258,8 +1397,11 @@ async function installAmazonQ(cwd = process.cwd()) {
  */
 async function installIntegrationTarget(target, cwd = process.cwd(), scope = 'project', { onSkip } = {}) {
   const { execute, buildPlans } = require('../integrations')
+  const { resolveAgentModels } = require('../config')
+  const { models: agentModels, warning: agentModelsWarning } = resolveAgentModels(scope, homedir(), cwd)
+  if (agentModelsWarning) process.stderr.write(agentModelsWarning + '\n')
   const roots = { projectRoot: cwd }
-  const options = { targets: [target], scope, onSkip }
+  const options = { targets: [target], scope, onSkip, agentModels }
   // D5 — transparency: print resolved destinations before writing anything.
   // buildPlans has no side effects, so it is safe to call here purely to
   // enumerate destinations; the actual write happens below via execute().
@@ -1292,7 +1434,7 @@ function generateClaudeCommandsForce(rootDir) {
  * installSkillsForce — sobrescreve ~/.claude/skills/trackfw/SKILL.md sempre.
  */
 function installSkillsForce() {
-  const skillDir = path.join(os.homedir(), '.claude', 'skills', 'trackfw')
+  const skillDir = path.join(homedir(), '.claude', 'skills', 'trackfw')
   fs.mkdirSync(skillDir, { recursive: true })
 
   const content = `---
@@ -1370,6 +1512,8 @@ module.exports = {
   generateClaudeCommands,
   generateClaudeCommandsForce,
   generateVaultIndex,
+  generateGitAttributes,
+  GITATTRIBUTES_BLOCK,
   installSkillsForce,
   installAgents,
   installGemini,
@@ -1383,4 +1527,12 @@ module.exports = {
   injectHooksDetected,
   trackfwRulesBlock,
   printArchitectNextSteps,
+  // Template constants and builders — exported for scaffold doctor (ADR-2026-08-27).
+  // Same single-source-of-truth principle as hooks.js exports: comparing against the
+  // same object the write path uses makes drift structurally impossible.
+  CLAUDE_COMMANDS,
+  buildValidateScript,
+  // CI workflow content builders (inline content from generateGitHub/GitLabCIWorkflow)
+  buildGitHubActionsWorkflowContent,
+  buildGitLabCIWorkflowContent,
 }

package/src/generators/req.js

@@ -4,66 +4,21 @@ const path = require('path')
 const { localDateISO } = require('./date')
 const roadmapGen = require('./roadmap')
 const config = require('../config')
+const { resolveAgentNamespaces, resolveReqFiles, reqWriteDir } = require('../validator')
+const { normalizeCRLF } = require('../integrations/render')
 
 const VALID_STATES = roadmapGen.VALID_STATES
 const STATE_ORDER = roadmapGen.STATE_ORDER
 
 /**
- * listREQFiles — descoberta recursiva de REQs nos 3 layouts suportados, mesmo algoritmo usado
- * em Go/Python (ADR-2026-08-04): flat (reqDir/*.md), por-estado (reqDir/<estado>/*.md) e,
- * quando roadmapNamespacing === 'by_agent', by_agent (reqDir/<agente>/<estado>/*.md).
- * Os três conjuntos não são mutuamente exclusivos — concatena todos.
+ * listREQFiles — NÃO reimplementa a descoberta: delega ao ponto único de leitura do validador
+ * (resolveReqFiles — ADR-2026-09-03, D3/D4), o mesmo consumido pelas regras de validate. Duas
+ * noções de layout no mesmo runtime foram a causa do defeito da REQ-2026-08-30.
  * @param {object} cfg — config completo (ver npm/src/config)
- * @returns {string[]} paths completos, na ordem flat → por-estado → by_agent
+ * @returns {string[]} paths completos, união dos 4 layouts, deduplicados e ordenados
  */
 function listREQFiles(cfg) {
-  const reqDir = cfg.reqDir
-  const files = []
-
-  // (a) flat legado — reqDir/*.md
-  try {
-    for (const f of fs.readdirSync(reqDir)) {
-      if (!f.endsWith('.md')) continue
-      const full = path.join(reqDir, f)
-      try {
-        if (!fs.statSync(full).isDirectory()) files.push(full)
-      } catch (_) { /* ignora */ }
-    }
-  } catch (_) { /* reqDir não existe */ }
-
-  // (b) por-estado, sem agente — reqDir/<estado>/*.md
-  for (const state of STATE_ORDER) {
-    const dir = path.join(reqDir, state)
-    try {
-      for (const f of fs.readdirSync(dir)) {
-        if (f.endsWith('.md')) files.push(path.join(dir, f))
-      }
-    } catch (_) { /* estado não existe */ }
-  }
-
-  // (c) by_agent — reqDir/<agente>/<estado>/*.md
-  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
-    let agents = cfg.agents || []
-    if (agents.length === 0) {
-      try {
-        agents = fs.readdirSync(reqDir).filter(f => {
-          try { return fs.statSync(path.join(reqDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) { agents = [] }
-    }
-    for (const agent of agents) {
-      for (const state of STATE_ORDER) {
-        const dir = path.join(reqDir, agent, state)
-        try {
-          for (const f of fs.readdirSync(dir)) {
-            if (f.endsWith('.md')) files.push(path.join(dir, f))
-          }
-        } catch (_) { /* agente/estado não existe */ }
-      }
-    }
-  }
-
-  return files
+  return resolveReqFiles(cfg)
 }
 
 /**
@@ -114,7 +69,11 @@ function parseREQStatus(filepath) {
   return 'unknown'
 }
 
+// D1/D3 (ADR-2026-09-04-parser-de-frontmatter-tolera-crlf-na-fronteira-de-entrada, ML-5B):
+// normaliza CRLF -> LF via normalizeCRLF na própria entrada, antes de qualquer casamento de
+// "---\n" — reaproveita a única implementação Node, sem criar uma segunda cópia.
 function rewriteREQStatus(source, status) {
+  source = normalizeCRLF(String(source))
   if (!source.startsWith('---\n')) return { content: source, changed: false }
   const end = source.slice(4).indexOf('\n---')
   if (end < 0) return { content: source, changed: false }
@@ -286,7 +245,10 @@ function toSlug(s) {
  * @returns {Promise<void>}
  */
 async function newREQ(content) {
-  const reqDir = require('../config').load().reqDir
+  // Ponto único de decisão de caminho de ESCRITA (ADR-2026-09-03, D2/D4): by_agent grava no
+  // canônico req_dir/<agente>/; flat grava em req_dir/ — o mesmo ponto que alimenta a união de leitura.
+  const cfg = require('../config').load()
+  const reqDir = reqWriteDir(cfg) || cfg.reqDir
   fs.mkdirSync(reqDir, { recursive: true })
 
   const slug = toSlug(content.title)