trackfw 7.3.0 → 7.4.0

package/src/generators/roadmap.js

@@ -3,7 +3,20 @@ const fs = require('fs')
 const path = require('path')
 const config = require('../config')
 const { localDateISO } = require('./date')
-const { resolveReqFiles } = require('../validator/index.js')
+const { resolveReqFiles, resolveAgentNamespaces } = require('../validator/index.js')
+const { normalizeRefSeparator: pathfmtNormalizeRefSeparator } = require('../lib/pathfmt')
+const { normalizeCRLF } = require('../integrations/render')
+
+// STATUS_LEGEND teaches the vocabulary the `barrier` parser accepts for "**Status:**"
+// (AC11, ADR decision 5): the canonical form the template now writes (⬜ Pendente) plus the
+// other three states. Placed once, right before the first wave, so it is close to the first
+// place a "**Status:**" line appears — not repeated per-ML (would clutter) and not left for
+// the end (nobody reads that far). Byte-identical across the 3 CLIs
+// (gate: scripts/check-artifact-parity.sh).
+const STATUS_LEGEND = `## Status Legend
+⬜ Pendente · 🔄 Em andamento · ✅ Concluído · ❌ Bloqueado
+
+`
 
 // wave0Block — "## Wave 0 — Threat Model" section prepended to every generated roadmap, before
 // the first implementation wave (AC1, AC12). Byte-identical to internal/generators/roadmap.go's
@@ -17,11 +30,11 @@ const { resolveReqFiles } = require('../validator/index.js')
 //
 // The ML is always ML-0A, never ML-1A — newRoadmapFromReq labels MLs derived from REQ acceptance
 // criteria "ML-1A", "ML-1B", ... starting at the first criterion.
-const WAVE0_BLOCK = `## Wave 0 — Threat Model
+const WAVE0_BLOCK = STATUS_LEGEND + `## Wave 0 — Threat Model
 > Dependencies: none. Blocks all implementation.
 
 ### ML-0A — Threat model for this roadmap
-**Status:** pending
+**Status:** ⬜ Pendente
 **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).
@@ -77,14 +90,7 @@ function listRoadmaps() {
   let found = false
 
   if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
-    let agents = cfg.agents || []
-    if (agents.length === 0) {
-      try {
-        agents = fs.readdirSync(cfg.roadmapDir).filter(f => {
-          try { return fs.statSync(path.join(cfg.roadmapDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) { agents = [] }
-    }
+    const agents = resolveAgentNamespaces(cfg, cfg.roadmapDir)
     for (const agent of agents) {
       for (const state of STATE_ORDER) {
         const dir = cfg.roadmapDir + '/' + agent + '/' + state
@@ -166,9 +172,14 @@ function showRoadmap(name) {
  * antes do primeiro "## " heading é atualizada.
  *
  * Retorna { content: string, changed: boolean }.
+ *
+ * D1/D3 (ADR-2026-09-04-parser-de-frontmatter-tolera-crlf-na-fronteira-de-entrada, ML-5B):
+ * normaliza CRLF -> LF via normalizeCRLF (npm/src/integrations/render.js) na própria entrada,
+ * antes de qualquer casamento de "---\n" — reaproveita a única implementação Node, sem criar
+ * uma segunda cópia.
  */
 function rewriteRoadmapStatus(source, state) {
-  const s = String(source)
+  const s = normalizeCRLF(String(source))
   if (!s.startsWith('---\n')) return { content: s, changed: false }
   const end = s.indexOf('\n---', 4)
   if (end < 0) return { content: s, changed: false }
@@ -289,8 +300,29 @@ function moveRoadmap(name, state) {
   appendTransitionLog(logBasename, fromState, state)
   console.log(`✓ moved ${basename} → ${targetDir}`)
 
-  // Sincroniza o roadmap: das REQs que apontem para este roadmap.
-  syncReqReferences(basename, dst, cfg)
+  // Sincroniza o roadmap: das REQs que apontem para este roadmap. O valor escrito no
+  // frontmatter da REQ pareada é dado portável, nunca separador nativo — normaliza antes de
+  // sincronizar (dst continua nativo acima, para rename/read/write no filesystem).
+  syncReqReferences(basename, normalizeRefSeparator(dst), cfg)
+}
+
+/**
+ * normalizeRefSeparator — normaliza um valor já extraído (não o buffer inteiro do arquivo)
+ * para o separador portável (/) antes de ele ser escrito ou comparado como referência dentro
+ * de conteúdo versionado. Substituição incondicional: em POSIX, path.join nunca produz "\",
+ * então isto só atua sobre um valor herdado de um commit feito no Windows — exatamente o
+ * defeito que esta função existe para curar
+ * (docs/seguranca/2026-09-01-modelo-de-ameaca-do-separador-em-artefato.md).
+ * @param {string} p
+ * @returns {string}
+ */
+function normalizeRefSeparator(p) {
+  // Delegação ao ponto único do runtime (ADR-2026-09-04, D3). A função continua
+  // exportada daqui porque consumidores e testes já a importam por este caminho;
+  // a IMPLEMENTAÇÃO agora é uma só, em npm/src/lib/pathfmt.js, para que o CLI Node
+  // não tenha duas noções de formato — a origem documentada das ocorrências de
+  // gerador e verificador discordando.
+  return pathfmtNormalizeRefSeparator(p)
 }
 
 /**
@@ -342,11 +374,30 @@ function extractFrontmatterRoadmap(content) {
  * rewriteReqRoadmapRef — reescreve o campo `roadmap:` no frontmatter e a linha `Roadmap:` no
  * corpo de uma REQ, substituindo oldRef por newRef.
  * Preserva toda formatação existente (aspas, backticks) via substituição literal de string.
+ *
+ * D2/D3 (ADR-2026-09-04-parser-de-frontmatter-tolera-crlf-na-fronteira-de-entrada, ML-5D):
+ * normaliza CRLF -> LF via normalizeCRLF na própria entrada, antes de qualquer split por "\n"
+ * — mesmo ponto único Node reaproveitado por rewriteRoadmapStatus/rewriteREQStatus. Sem isto,
+ * um REQ gravado com CRLF (Windows) tinha as linhas RESCRITAS saindo em LF (via .replace) e as
+ * linhas NÃO tocadas saindo com o "\r" original ainda embutido no elemento que o split
+ * preservava — join produzia um arquivo com terminador MISTO. Medido com o binário real
+ * (ML-5C): 10 bytes "\r" vazados na REQ reescrita por `roadmap move`.
+ *
+ * 🔴 Se nenhuma linha REALMENTE muda (comparando o texto produzido com a linha original, não
+ * apenas "houve match de oldRef"), devolve o `content` ORIGINAL (não normalizado), não o
+ * resultado da normalização. Isto importa porque o chamador da guarda de idempotência
+ * (syncReqReferences) invoca esta função com oldRef === newRef — um "replace" sem-efeito, que
+ * bate no ramo de match mas não deve contar como mudança. O único chamador detecta "nada a
+ * escrever" comparando `updated === content` por igualdade de string, não por um bool de
+ * "changed" explícito — normalizar incondicionalmente quebraria a cardinalidade "já correta →
+ * nenhuma escrita" (contrato pinado em docs/cli-parity.md) para qualquer REQ com CRLF em outro
+ * trecho do arquivo, mesmo quando o campo roadmap: já está correto.
  */
 function rewriteReqRoadmapRef(content, oldRef, newRef) {
-  const lines = content.split('\n')
+  const lines = normalizeCRLF(String(content)).split('\n')
   let inFm = false
   let fmDone = false
+  let changed = false
   const result = []
 
   for (let i = 0; i < lines.length; i++) {
@@ -356,7 +407,9 @@ function rewriteReqRoadmapRef(content, oldRef, newRef) {
     if (inFm) {
       const idx = line.indexOf(':')
       if (idx !== -1 && line.slice(0, idx).trim() === 'roadmap' && line.includes(oldRef)) {
-        result.push(line.replace(oldRef, newRef))
+        const newLine = line.replace(oldRef, newRef)
+        if (newLine !== line) changed = true
+        result.push(newLine)
         continue
       }
       result.push(line)
@@ -365,13 +418,16 @@ function rewriteReqRoadmapRef(content, oldRef, newRef) {
     if (fmDone) {
       // No corpo: reescreve linhas `Roadmap:` que contenham oldRef
       if (line.trim().toLowerCase().startsWith('roadmap:') && line.includes(oldRef)) {
-        result.push(line.replace(oldRef, newRef))
+        const newLine = line.replace(oldRef, newRef)
+        if (newLine !== line) changed = true
+        result.push(newLine)
         continue
       }
     }
     result.push(line)
   }
 
+  if (!changed) return String(content)
   return result.join('\n')
 }
 
@@ -410,7 +466,10 @@ function syncReqReferences(movedBasename, newRoadmapPath, cfg) {
 
     const currentRef = extractFrontmatterRoadmap(content)
     if (!currentRef) continue
-    if (path.basename(currentRef) !== movedBasename) continue // aponta para outro roadmap
+    // path.basename sobre um valor sujo com "\" (gravado no Windows antes do fix de escrita)
+    // não separa nada em POSIX — normaliza antes de comparar, senão uma REQ já suja nunca é
+    // curada por um roadmap move subsequente.
+    if (path.basename(normalizeRefSeparator(currentRef)) !== movedBasename) continue // aponta para outro roadmap
     if (currentRef === newRoadmapPath) {
       // Guarda rápida: frontmatter já correto — confirma idempotência com reescrita estrutural
       const updated = rewriteReqRoadmapRef(content, currentRef, newRoadmapPath)
@@ -489,7 +548,7 @@ ${WAVE0_BLOCK}## Wave 1 — <name> (parallel MLs)
 > Dependencies: none
 
 ### ML-1A — ${title}
-**Status:** pending
+**Status:** ⬜ Pendente
 **Files affected:**
 **Actions:**
 **Acceptance criteria:**
@@ -552,7 +611,7 @@ function newRoadmapFromReq(reqPath) {
     const mlLabel = `ML-1${String.fromCharCode(65 + i)}`
     const crit = criteria[i]
     mlLines.push(`\n### ${mlLabel} — ${crit}`)
-    mlLines.push('**Status:** pending')
+    mlLines.push('**Status:** ⬜ Pendente')
     mlLines.push('**Files affected:**')
     mlLines.push('**Actions:**')
     mlLines.push('**Acceptance criteria:**')
@@ -655,14 +714,7 @@ function findRoadmapMatches(name) {
   const nameLower = name.toLowerCase()
 
   if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
-    let agents = cfg.agents || []
-    if (agents.length === 0) {
-      try {
-        agents = fs.readdirSync(cfg.roadmapDir).filter(f => {
-          try { return fs.statSync(path.join(cfg.roadmapDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) { agents = ['default'] }
-    }
+    const agents = resolveAgentNamespaces(cfg, cfg.roadmapDir)
     for (const agent of agents) {
       for (const state of STATE_ORDER) {
         const dir = cfg.roadmapDir + '/' + agent + '/' + state
@@ -712,6 +764,7 @@ module.exports = {
   extractFrontmatterRoadmap,
   rewriteReqRoadmapRef,
   syncReqReferences,
+  normalizeRefSeparator,
   newRoadmap,
   newRoadmapFromReq,
   stateDir,

package/src/homedir.js

@@ -0,0 +1,30 @@
+'use strict'
+
+/**
+ * homedir.js — resolves the user's home directory consistently across platforms.
+ *
+ * Mirrors internal/homedir/homedir.go (Go, canonical source of truth) and
+ * pypi/trackfw/homedir.py (Python). See that file's doc comment for the full
+ * rationale.
+ *
+ * Why it exists: os.homedir() reads $HOME on Linux and macOS, but %USERPROFILE%
+ * on Windows. Tests and gates isolate the home directory with HOME=<tempdir>,
+ * which on Windows isolates nothing — the process keeps reading and writing the
+ * developer's real home.
+ *
+ * homedir() makes Windows behave like the other platforms: $HOME first,
+ * os.homedir() as the fallback. Where $HOME is unset nothing changes.
+ *
+ * The empty string does NOT count as set: HOME="" would resolve to "" and every
+ * derived path would silently become relative.
+ */
+
+const os = require('os')
+
+function homedir() {
+  const fromEnv = process.env.HOME
+  if (fromEnv) return fromEnv
+  return os.homedir()
+}
+
+module.exports = { homedir }

package/src/integrations/doctor_remote.js

@@ -0,0 +1,224 @@
+'use strict'
+
+// Mirrors internal/commands/doctor_remote.go (Go, canonical source of truth for wording/
+// semantics) — see that file's doc comments for the full rationale. Implements the --remote
+// modality of `trackfw doctor` (ADR-2026-09-02, ML-3A): GitHub branch protection
+// (required_status_checks, enforce_admins) plus local core.hooksPath neutralization. Never
+// runs unless explicitly requested via --remote.
+
+const { spawnSync } = require('child_process')
+const {
+  REQUIRED_STATUS_CHECKS_MISSING,
+  ENFORCE_ADMINS_DISABLED,
+  HOOKS_PATH_NEUTRALIZED,
+  NOT_EVALUATED,
+} = require('./doctor')
+const { resolve: resolveForge } = require('../forge/resolve')
+const { forgeAdapter } = require('../forge/adapter')
+
+// defaultExecGit runs a git command and returns { stdout, error } — stdout trimmed, error null
+// on success. Mirrors release/runner.js's defaultExecGit.
+function defaultExecGit(args) {
+  const result = spawnSync('git', args, { encoding: 'utf8' })
+  if (result.status !== 0) {
+    const msg = (result.stderr || '').trim() || `git ${args.join(' ')} exited with ${result.status}`
+    return { stdout: '', error: new Error(msg) }
+  }
+  return { stdout: (result.stdout || '').trim(), error: null }
+}
+
+// defaultExecForgeAPI runs a forge CLI command (gh api ...) and returns { stdout, error }.
+// Mirrors release/runner.js's defaultExecForgeAPI.
+function defaultExecForgeAPI(name, args, stdin) {
+  const result = spawnSync(name, args, { input: stdin || '', encoding: 'utf8' })
+  if (result.status !== 0) {
+    const msg = (result.stderr || '').trim() || `${name} ${args.join(' ')} exited with ${result.status}`
+    return { stdout: (result.stdout || '').trim(), error: new Error(msg) }
+  }
+  return { stdout: (result.stdout || '').trim(), error: null }
+}
+
+// Values that discard every git hook invocation on each OS git supports as a hooksPath target.
+// Anything else (including unset) is left alone — a custom husky/lefthook directory is
+// legitimate and must never be flagged.
+const NEUTRALIZED_HOOKS_PATH_VALUES = new Set(['/dev/null', 'NUL'])
+
+/**
+ * runDoctorRemote implements the --remote modality: every branch either produces a genuine
+ * finding (evaluated, and wrong) or a NOT_EVALUATED finding (could not evaluate) — never
+ * silence, which would read as "ok" to a report that treats an empty finding list as a clean
+ * bill of health.
+ *
+ * @param {object} deps
+ * @param {function} [deps.execGit] - (args: string[]) => { stdout, error }
+ * @param {function} [deps.execForgeAPI] - (name, args, stdin) => { stdout, error }
+ * @param {function} [deps.availFn] - (name: string) => boolean
+ * @param {string} [deps.configForge] - forge: field from trackfw.yaml
+ * @param {string} [deps.repoDir] - repo root, for CI file detection during forge resolution
+ * @returns {Array<object>} findings
+ */
+function runDoctorRemote(deps = {}) {
+  const execGit = deps.execGit || defaultExecGit
+  const execForgeAPI = deps.execForgeAPI || defaultExecForgeAPI
+  const availFn = deps.availFn
+  const configForge = deps.configForge || ''
+  const repoDir = deps.repoDir !== undefined ? deps.repoDir : ''
+
+  const findings = []
+
+  // ── Local check: core.hooksPath neutralized (no network needed) ──────────────────────
+  const hooksPathResp = execGit(['config', '--get', 'core.hooksPath'])
+  if (!hooksPathResp.error && NEUTRALIZED_HOOKS_PATH_VALUES.has(hooksPathResp.stdout.trim())) {
+    findings.push({
+      finding: HOOKS_PATH_NEUTRALIZED,
+      destination: 'git:core.hooksPath',
+      remedy: `git config --unset core.hooksPath   # currently "${hooksPathResp.stdout.trim()}" discards every hook invocation; unset to restore .git/hooks, or point it at your real hooks directory`,
+    })
+  }
+
+  // ── Forge resolution: only GitHub is evaluated; every other forge is not applicable ──
+  const remoteURLResp = execGit(['remote', 'get-url', 'origin'])
+  const remoteURL = remoteURLResp.error ? '' : remoteURLResp.stdout.trim()
+  let resolution
+  try {
+    resolution = resolveForge({ configForge, remoteURL, repoDir })
+  } catch (e) {
+    findings.push({
+      finding: NOT_EVALUATED,
+      destination: 'branch-protection',
+      remedy: `not applicable: branch protection is checked only on GitHub, and this repository's forge resolved to "unknown". Not a failure — no action needed unless this repository is actually hosted on GitHub, in which case set forge: github in trackfw.yaml or add a github.com origin remote.`,
+    })
+    return findings
+  }
+  if (resolution.forge !== 'github') {
+    findings.push({
+      finding: NOT_EVALUATED,
+      destination: 'branch-protection',
+      remedy: `not applicable: branch protection is checked only on GitHub, and this repository's forge resolved to "${resolution.forge}". Not a failure — no action needed unless this repository is actually hosted on GitHub, in which case set forge: github in trackfw.yaml or add a github.com origin remote.`,
+    })
+    return findings
+  }
+
+  // ── gh CLI availability ───────────────────────────────────────────────────────────────
+  const adapter = forgeAdapter('github', availFn)
+  if (!adapter.available) {
+    findings.push({
+      finding: NOT_EVALUATED,
+      destination: 'branch-protection',
+      remedy: 'install the GitHub CLI (gh) to evaluate branch protection remotely: https://cli.github.com, then retry with --remote',
+    })
+    return findings
+  }
+
+  // ── Credential presence: distinct from credential SCOPE below (ADR-2026-09-02) ────────
+  const authResp = execForgeAPI('gh', ['auth', 'status'], '')
+  if (authResp.error) {
+    findings.push({
+      finding: NOT_EVALUATED,
+      destination: 'branch-protection',
+      remedy: 'GitHub CLI has no credential — authenticate first: gh auth login (or set GITHUB_TOKEN/GH_TOKEN), then retry with --remote',
+    })
+    return findings
+  }
+
+  // ── Repository info: default branch + whether this credential has admin access ────────
+  const repoInfoResp = execForgeAPI('gh', ['api', 'repos/{owner}/{repo}'], '')
+  if (repoInfoResp.error) {
+    findings.push({
+      finding: NOT_EVALUATED,
+      destination: 'branch-protection',
+      remedy: `could not reach the GitHub API to resolve this repository: ${repoInfoResp.error.message}. Check network connectivity and retry with --remote`,
+    })
+    return findings
+  }
+  let repoInfo
+  try {
+    repoInfo = JSON.parse(repoInfoResp.stdout)
+  } catch (e) {
+    repoInfo = null
+  }
+  if (!repoInfo || !repoInfo.default_branch) {
+    findings.push({
+      finding: NOT_EVALUATED,
+      destination: 'branch-protection',
+      remedy: `could not parse the repository response from the GitHub API: ${repoInfoResp.stdout}. Retry with --remote`,
+    })
+    return findings
+  }
+
+  // Credential SCOPE: reading branch protection requires admin access to the repository.
+  // Distinct remedy from "no credential" above — one is fixed by authenticating, this one by
+  // being granted admin access (or using a token for a repo you administer).
+  const isAdmin = Boolean(repoInfo.permissions && repoInfo.permissions.admin)
+  if (!isAdmin) {
+    findings.push({
+      finding: NOT_EVALUATED,
+      destination: 'branch-protection',
+      remedy: 'the authenticated GitHub credential lacks admin access to this repository — reading branch protection requires it. Ask a repository admin to grant access, or authenticate as an account that has it, then retry with --remote',
+    })
+    return findings
+  }
+
+  // ── Branch protection itself ────────────────────────────────────────────────────────────
+  const defaultBranch = repoInfo.default_branch
+  const protectionResp = execForgeAPI('gh', ['api', `repos/{owner}/{repo}/branches/${defaultBranch}/protection`], '')
+  if (protectionResp.error) {
+    if (protectionResp.error.message.includes('(HTTP 404)')) {
+      // Evaluated (admin confirmed above): the branch genuinely has no protection at all,
+      // which means both checks fail — GitHub does not return the two settings separately
+      // when there is no rule to read them from.
+      findings.push({
+        finding: REQUIRED_STATUS_CHECKS_MISSING,
+        destination: `branch-protection:${defaultBranch}:required_status_checks`,
+        remedy: `configure required status checks: GitHub repo Settings > Branches > Branch protection rules > ${defaultBranch} > Require status checks to pass before merging`,
+      })
+      findings.push({
+        finding: ENFORCE_ADMINS_DISABLED,
+        destination: `branch-protection:${defaultBranch}:enforce_admins`,
+        remedy: `gh api repos/{owner}/{repo}/branches/${defaultBranch}/protection/enforce_admins --method POST`,
+      })
+      return findings
+    }
+    findings.push({
+      finding: NOT_EVALUATED,
+      destination: `branch-protection:${defaultBranch}`,
+      remedy: `could not read branch protection from the GitHub API: ${protectionResp.error.message}. This may be transient (rate limit, network) — retry with --remote`,
+    })
+    return findings
+  }
+
+  let protection
+  try {
+    protection = JSON.parse(protectionResp.stdout)
+  } catch (e) {
+    findings.push({
+      finding: NOT_EVALUATED,
+      destination: `branch-protection:${defaultBranch}`,
+      remedy: `could not parse the branch protection response from the GitHub API: ${protectionResp.stdout}. Retry with --remote`,
+    })
+    return findings
+  }
+
+  const rsc = protection.required_status_checks
+  const contexts = (rsc && rsc.contexts) || []
+  const checks = (rsc && rsc.checks) || []
+  if (!rsc || (contexts.length === 0 && checks.length === 0)) {
+    findings.push({
+      finding: REQUIRED_STATUS_CHECKS_MISSING,
+      destination: `branch-protection:${defaultBranch}:required_status_checks`,
+      remedy: `configure required status checks: GitHub repo Settings > Branches > Branch protection rules > ${defaultBranch} > Require status checks to pass before merging`,
+    })
+  }
+  const enforceAdmins = protection.enforce_admins
+  if (!enforceAdmins || !enforceAdmins.enabled) {
+    findings.push({
+      finding: ENFORCE_ADMINS_DISABLED,
+      destination: `branch-protection:${defaultBranch}:enforce_admins`,
+      remedy: `gh api repos/{owner}/{repo}/branches/${defaultBranch}/protection/enforce_admins --method POST`,
+    })
+  }
+
+  return findings
+}
+
+module.exports = { runDoctorRemote, defaultExecGit, defaultExecForgeAPI }

package/src/integrations/index.js

@@ -9,6 +9,7 @@ const { legacyHashes } = require('./legacy')
 const identityStore = require('../identity')
 const { injectRulesForTool } = require('../generators/init')
 const { applyThirdPartyReferences } = require('../thirdparty/references')
+const { homedir } = require('../homedir')
 
 function parseSurfaces(values = []) {
   const result = {}
@@ -109,7 +110,7 @@ function execute(kind, operation, options = {}, roots = {}) {
   // reverteria silenciosamente os nomes customizados dos agentes para os
   // defaults neutros (espelha internal/commands/integrations_flags.go:
   // executeIntegrationMutation/executeIntegrationList).
-  const homeRoot = roots.homeRoot || os.homedir()
+  const homeRoot = roots.homeRoot || homedir()
   const identityConfig = options.identity !== undefined ? options.identity : identityStore.load(homeRoot)
   const manager = new IntegrationManager(roots, { onSkip: options.onSkip })
   // D5/D9: manager.roots.project lets buildPlans reproduce any persisted

package/src/integrations/manager.js

@@ -7,6 +7,8 @@ const path = require('node:path')
 
 const { frontmatterName } = require('./render')
 const { tildeify } = require('../lib/update-engine')
+const { normalizeRefSeparator } = require('../lib/pathfmt')
+const { homedir } = require('../homedir')
 
 const SCHEMA_VERSION = 1
 const sha256 = content => crypto.createHash('sha256').update(content).digest('hex')
@@ -27,7 +29,7 @@ const cleanClaim = claim => {
 }
 
 class IntegrationManager {
-  constructor({ projectRoot = process.cwd(), homeRoot = os.homedir() } = {}, { onSkip } = {}) {
+  constructor({ projectRoot = process.cwd(), homeRoot = homedir() } = {}, { onSkip } = {}) {
     this.roots = { project: path.resolve(projectRoot), global: path.resolve(homeRoot) }
     this.onSkip = onSkip
     // _afterManifestPersist, when set, runs immediately after manifests are
@@ -411,9 +413,15 @@ class IntegrationManager {
   // - scope global: substitui homeRoot por '~' (via tildeify, com salvaguarda
   //   de barra dupla corrigida no ML-6H).
   // - scope de projeto: caminho relativo ao projectRoot, sem './' prefixo.
+  // ML-2A: o ramo global ja sai normalizado (tildeify normaliza os 3 retornos);
+  // o ramo de projeto precisa da normalizacao aqui, porque path.relative devolve
+  // separador nativo. Os dois sao EMISSAO — o valor vai so para a mensagem de
+  // warning entregue a onSkip, que o escreve verbatim em stderr (ADR-2026-09-04,
+  // D1 categoria 1). O par Python (integrations/manager.py) ja emitia "/" via
+  // .as_posix(); Node e Go eram a divergencia (D4).
   tildeAbbrev(file, scope) {
     if (scope === 'global') return tildeify(this.roots.global, file)
-    return path.relative(this.roots.project, file)
+    return normalizeRefSeparator(path.relative(this.roots.project, file))
   }
 
   cleanEmpty(directory, root) {

package/src/integrations/render.js

@@ -34,8 +34,39 @@ function normalize(content) {
   return `${content.trim()}\n`
 }
 
+// normalizeCRLF converte "\r\n" em "\n" na fronteira em que o conteúdo cru de
+// um agent-md entra num parser ou reescritor de frontmatter (ADR
+// ADR-2026-09-04-parser-de-frontmatter-tolera-crlf-na-fronteira-de-entrada,
+// D1/D3). Um source CRLF é entrada válida, não erro: `String.prototype.trim`
+// só remove whitespace das pontas, então um "---\r\n" interno sobrevive ao
+// `.trim()` e falsifica todo `startsWith('---\n')` deste arquivo — é
+// exatamente o defeito medido (frontmatter inteiro cai no corpo).
+//
+// Única implementação desta normalização neste runtime (D3): cada função de
+// fronteira de frontmatter deste arquivo (markdownParts,
+// rewriteFrontmatterModelLine, removeFrontmatterModelLine, insertBodyPrefix,
+// rewriteSignatureLine, rewriteFrontmatterFields, frontmatterName) chama esta
+// função na própria entrada, porque este módulo não tem uma única leitura de
+// I/O compartilhada por todas elas — render(), manager.js e o consumidor de
+// AgentTier entram por pontos distintos. Espelha
+// internal/integrations/render.go:normalizeCRLF.
+//
+// D2: só a leitura é afetada. Toda reescrita deste arquivo reconstrói a
+// saída com `.join('\n')`, então normalizar a entrada para LF aqui não
+// autoriza emitir CRLF — a saída permanece LF independente do terminador de
+// linha da entrada.
+//
+// D4/escopo: só "\r\n" vira "\n". Um "\r" solto (Mac clássico, sem "\n") é
+// deixado intocado de propósito, conforme o não-objetivo declarado na ADR.
+//
+// Reaproveitada por npm/src/generators/roadmap.js e npm/src/generators/req.js (ML-5B,
+// rewriteRoadmapStatus/rewriteREQStatus) — mesma implementação Node, não uma segunda cópia.
+function normalizeCRLF(content) {
+  return String(content).replace(/\r\n/g, '\n')
+}
+
 function markdownParts(content) {
-  const text = content.trim()
+  const text = normalizeCRLF(content).trim()
   let name = 'trackfw-agent'
   let description = 'trackfw specialist'
   let model = ''
@@ -126,7 +157,7 @@ function rewriteFrontmatterModelLine(source, value) {
   if (containsControlChar(value)) {
     throw new Error(`model value contains control character and was rejected: model IDs never require newlines or other control characters (got ${JSON.stringify(value)})`)
   }
-  const trimmed = String(source).trim()
+  const trimmed = normalizeCRLF(source).trim()
   if (!trimmed.startsWith('---\n')) return trimmed
   const end = trimmed.indexOf('\n---', 4)
   if (end < 0) return trimmed
@@ -156,7 +187,7 @@ function rewriteFrontmatterModelLine(source, value) {
 // reconhecível, source é retornado sem alteração (trimado). Espelha
 // internal/integrations/render.go:removeFrontmatterModelLine.
 function removeFrontmatterModelLine(source) {
-  const trimmed = String(source).trim()
+  const trimmed = normalizeCRLF(source).trim()
   if (!trimmed.startsWith('---\n')) return trimmed
   const end = trimmed.indexOf('\n---', 4)
   if (end < 0) return trimmed
@@ -197,7 +228,7 @@ function greetingLine(displayName, nickname) {
 // markdownParts, para que Rota A e Rota B concordem sobre onde o corpo
 // começa. Espelha internal/integrations/render.go:insertBodyPrefix.
 function insertBodyPrefix(source, prefix) {
-  const trimmed = String(source).trim()
+  const trimmed = normalizeCRLF(source).trim()
   if (!prefix) return trimmed
   if (!trimmed.startsWith('---\n')) return `${prefix}\n\n${trimmed}`
   const end = trimmed.indexOf('\n---', 4)
@@ -226,7 +257,7 @@ function insertBodyPrefix(source, prefix) {
 // Espelha internal/integrations/render.go:rewriteSignatureLine.
 function rewriteSignatureLine(source, displayName) {
   if (!displayName) return source
-  const trimmed = String(source).trim()
+  const trimmed = normalizeCRLF(source).trim()
 
   // Localiza o início do corpo — espelha a detecção de fronteira de
   // rewriteFrontmatterFields para que o escopo de ambas as funções coincida.
@@ -269,7 +300,7 @@ function rewriteSignatureLine(source, displayName) {
 // frontmatter reconhecível, source é retornado sem alteração (trimado).
 // Espelha internal/integrations/render.go:rewriteFrontmatterFields.
 function rewriteFrontmatterFields(source, name, description) {
-  const trimmed = String(source).trim()
+  const trimmed = normalizeCRLF(source).trim()
   if (!trimmed.startsWith('---\n')) return trimmed
   const end = trimmed.indexOf('\n---', 4)
   if (end < 0) return trimmed
@@ -298,7 +329,7 @@ function rewriteFrontmatterFields(source, name, description) {
 // declara "name". Usado pela detecção de colisão em manager.js. Espelha
 // internal/integrations/render.go:frontmatterName.
 function frontmatterName(content) {
-  const text = String(content).trim()
+  const text = normalizeCRLF(content).trim()
   if (!text.startsWith('---\n')) return undefined
   const end = text.indexOf('\n---', 4)
   if (end < 0) return undefined
@@ -529,4 +560,4 @@ function looksLikeSuspectModelValue(v) {
   return containsControlChar(v) || (!isVersionString(v) && !v.startsWith('claude-'))
 }
 
-module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields, rewriteFrontmatterModelLine, rewriteSignatureLine, isVersionString, composeClaudeModelID, resolveAgentModel, looksLikeSuspectModelValue }
+module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields, rewriteFrontmatterModelLine, rewriteSignatureLine, isVersionString, composeClaudeModelID, resolveAgentModel, looksLikeSuspectModelValue, normalizeCRLF }

package/src/integrations/scaffold_doctor.js

@@ -44,6 +44,10 @@ const { SIGNAL_SCRIPT, CLEANUP_SCRIPT, CREDENTIAL_GUARD_SCRIPT, GIT_BRANCH_GUARD
   require('../generators/hooks')
 const { CLAUDE_COMMANDS, buildValidateScript, buildGitHubActionsWorkflowContent, buildGitLabCIWorkflowContent } =
   require('../generators/init')
+const {
+  buildDiscoverGitHubActionsWorkflowContent,
+  DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH,
+} = require('../commands/discover')
 
 // Finding kind constants — mirrors Go's DoctorScaffoldDivergent / DoctorScaffoldMissing /
 // DoctorScaffoldWrongMode.
@@ -349,6 +353,31 @@ function runScaffoldDoctor(projectRoot) {
     if (f) findings.push(f)
   }
 
+  // --- Discover CI workflow (second, independent install mechanism) ---
+  //
+  // trackfw-validate.yml (written by `trackfw discover --init`, installGates) is a
+  // separate artifact from trackfw-gate.yml above — both can coexist in the same
+  // project (ADR-2026-08-28). Only checked when the file is already present, mirroring
+  // the "conditional artifact" treatment of trackfw-gate.yml above but using
+  // presence-on-disk instead of cfg.ci, because installGates decides on its own
+  // discovery signal (github-actions detection), not on trackfw.yaml's `ci:` key — a
+  // project can have discover's workflow without cfg.ci ever being set.
+  let discoverWorkflowExists = false
+  try {
+    fs.statSync(path.join(projectRoot, DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH))
+    discoverWorkflowExists = true
+  } catch (_) {}
+  if (discoverWorkflowExists) {
+    const f = checkScaffoldArtifact(
+      path.join(projectRoot, DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH),
+      DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH,
+      buildDiscoverGitHubActionsWorkflowContent(),
+      true,
+      false,
+    )
+    if (f) findings.push(f)
+  }
+
   // Deterministic output (AC7): sort by destination.
   findings.sort((a, b) => (a.destination < b.destination ? -1 : a.destination > b.destination ? 1 : 0))