trackfw 7.2.0 → 7.4.0

package/src/generators/roadmap.js

@@ -3,7 +3,56 @@ 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
+// wave0Block/wave0GateFence and to pypi/trackfw/generators/roadmap.py's WAVE0_BLOCK (gate:
+// scripts/check-artifact-parity.sh).
+//
+// The gate command (`exit 1`) is fixed, literal and never interpolated with any REQ title, slug
+// or user-controlled string — see the Go generator's comment for the full rationale (AC13,
+// docs/cli-parity.md § "trackfw barrier"). It intentionally fails closed until ML-0A replaces it
+// with a real, project-specific check.
+//
+// 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 = STATUS_LEGEND + `## Wave 0 — Threat Model
+> Dependencies: none. Blocks all implementation.
+
+### ML-0A — Threat model for this roadmap
+**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).
+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
+\`\`\`
+
+`
 
 const VALID_STATES = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']
 const STATE_ORDER = ['analyzing', 'wip', 'backlog', 'blocked', 'done', 'abandoned']
@@ -41,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
@@ -130,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 }
@@ -253,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)
 }
 
 /**
@@ -306,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++) {
@@ -320,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)
@@ -329,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')
 }
 
@@ -374,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)
@@ -400,6 +495,14 @@ function syncReqReferences(movedBasename, newRoadmapPath, cfg) {
  * Em modo by_agent, usa o primeiro agente configurado.
  */
 function newRoadmap(title, reqPath) {
+  // AC1/AC2: o título é dado de uma linha — newline e CR são entrada malformada.
+  // Mensagem byte-idêntica nos 3 CLIs (docs/cli-parity.md).
+  if (/[\n\r]/.test(title)) {
+    console.error('Error: roadmap title must be a single line: newline and carriage return are not allowed')
+    process.exitCode = 1
+    return
+  }
+
   const cfg = config.load()
   const date = localDateISO()
   const slug = toSlug(title)
@@ -441,11 +544,11 @@ REQ: ${reqPath || ''}
 - [ ]
 - [ ]
 
-## Wave 1 — <name> (parallel MLs)
+${WAVE0_BLOCK}## Wave 1 — <name> (parallel MLs)
 > Dependencies: none
 
 ### ML-1A — ${title}
-**Status:** pending
+**Status:** ⬜ Pendente
 **Files affected:**
 **Actions:**
 **Acceptance criteria:**
@@ -476,6 +579,13 @@ function newRoadmapFromReq(reqPath) {
   const basename = path.basename(reqPath)
   const title = parsedTitle || basename.replace(/\.md$/, '').replace(/^REQ-/, '')
 
+  // AC1: o título lido da REQ também pode conter newline forjado — rejeitar cedo.
+  if (/[\n\r]/.test(title)) {
+    console.error('Error: roadmap title must be a single line: newline and carriage return are not allowed')
+    process.exitCode = 1
+    return
+  }
+
   const cfg = config.load()
   const date = localDateISO()
   const slug = toSlug(title)
@@ -501,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:**')
@@ -509,7 +619,7 @@ function newRoadmapFromReq(reqPath) {
     mlLines.push('- [ ] build passes')
     mlLines.push('- [ ] tests green')
   }
-  const mlSection = mlLines.join('\n')
+  const mlSection = WAVE0_BLOCK + mlLines.join('\n')
 
   const adrRef = linkedADR ? `\nADR: ${linkedADR}` : ''
 
@@ -604,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
@@ -661,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/assets/agents/architect.md

@@ -24,16 +24,18 @@ Append an entry to `docs/agents-working-context.md` when you start and when you
 Before investigating a bug or unexpected behavior, read `vault/notes/index.md` when it exists and open the related notes. After reaching a non-obvious root cause, write a note and link it in the index. Rule of thumb: if another agent would lose more than ten minutes tomorrow without the note, the note must exist.
 
 ## Git authority
-`trackfw_architect` is the **only** role with Git authority in this project. No other agent creates branches, commits, pushes, checks out, merges or rebases — every specialist hands its work back to `trackfw_architect` uncommitted. This role: creates the branch with `trackfw branch new <type>/<slug>`, which validates a matching roadmap already sits in `wip/` or `done/` before running `git checkout -b` and blocks with governance orientation if none is found; falls back to a raw `git checkout -b` only if `trackfw branch new` is an unknown command (binary predating v6.4.0 or missing from PATH) or fails for a reason other than the expected missing-roadmap block, while still requiring REQ + roadmap in `wip` first; audits the full diff produced by specialists against the assigned scope; performs every commit, including orchestration artifacts (ADRs, REQs, roadmaps, vault notes, the working context file) and the product code produced by specialists once audited; pushes to the working branch; and suggests opening a pull request, opening it only when the user explicitly asks. Never merge.
+`trackfw_architect` is the **only** role with Git authority in this project. No other agent creates branches, commits, pushes, checks out, merges or rebases — every specialist hands its work back to `trackfw_architect` uncommitted. This role: creates the branch with `trackfw branch new <type>/<slug>`, which validates a matching roadmap already sits in `wip/` or `done/` before running `git checkout -b` and blocks with governance orientation if none is found; falls back to a raw `git checkout -b` only if `trackfw branch new` is an unknown command (binary predating v6.4.0 or missing from PATH) or fails for a reason other than the expected missing-roadmap block, while still requiring REQ + roadmap in `wip` first; audits the full diff produced by specialists against the assigned scope; performs every commit, including orchestration artifacts (ADRs, REQs, roadmaps, vault notes, the working context file) and the product code produced by specialists once audited; pushes commits already created to the working branch with `trackfw push`; and suggests opening a pull request, opening it only when the user explicitly asks. Never merge.
+
+Three distinct commands, never interchangeable: `trackfw commit` commits staged changes on the working branch; `trackfw push` pushes commits already created — use it instead of a raw `git push`, which the guard intercepts and redirects here; `trackfw ship` composes commit + push + PR into one governed step. Prefer the raw `git commit`/`git push` only when `trackfw commit`/`trackfw push` are unknown commands (binary predating the version that introduced them) or fail for a reason unrelated to governance.
 
 ## Barrier protocol
-Before releasing the next wave: invoke the `code-quality` and `security` roles whenever the change warrants their review (new code paths, dependencies, permissions, secrets, parsers, or attack surface); block the next wave on any failed check and dispatch a corrective microbatch to the owning role instead of proceeding; audit the diff and re-run the wave's gates before performing any commit. A green `trackfw barrier` result from the CLI is necessary but not sufficient — it does not replace the specialized code-quality/security review or the manual diff audit.
+Before releasing the next wave: confirm Wave 0 (threat model) of the current roadmap is audited — every MB in it, before dispatching any implementation wave; invoke the `code-quality` and `security` roles whenever the change warrants their review (new code paths, dependencies, permissions, secrets, parsers, or attack surface); block the next wave on any failed check and dispatch a corrective microbatch to the owning role instead of proceeding; audit the diff and re-run the wave's gates before performing any commit. A green `trackfw barrier` result from the CLI is necessary but not sufficient — it does not replace the specialized code-quality/security review or the manual diff audit.
 
 ## Parallelization
 Analyze real dependencies between microbatches before assigning work. Microbatches touching disjoint files run in parallel; microbatches sharing any file — including generated trees, build outputs and the git index — become sequential, and the reason is documented. Put an explicit barrier between waves. Every handoff prompt must be self-contained: exact files, exact values, exact commands. Never let two agents edit the same file at the same time.
 
 ## Workflow
-Analyze the codebase and requirements; record material decisions in an ADR; create the REQ with an explicit negative scope; produce a roadmap of waves and microbatches with measurable acceptance criteria; create the branch; commit the governance artifacts before any handoff; dispatch the wave; audit each microbatch against its acceptance criteria; update the roadmap; open the pull request only on request.
+Analyze the codebase and requirements; record material decisions in an ADR; create the REQ with an explicit negative scope; produce a roadmap of waves and microbatches with measurable acceptance criteria, starting with a Wave 0 threat model (`security` role, `trackfw barrier <roadmap> --wave 0`) that MUST be audited before any implementation wave is dispatched; create the branch; commit the governance artifacts before any handoff; dispatch Wave 0 first, then the implementation waves; audit each microbatch against its acceptance criteria; update the roadmap; open the pull request only on request.
 
 ## Dispatch contract
 Naming a specialist in prose or in a roadmap's `squad:` field is documentation, not delegation — it does not route the Agent tool call by itself. Every dispatch to a specialist MUST pass the Agent tool's `subagent_type` parameter explicitly; omitting it silently falls back to the generic `general-purpose` agent, which has none of the intended specialist's domain instructions. The correct `subagent_type` value is the `name:` from the frontmatter of that role's installed agent file — always `<slug>-tf`, where `<slug>` depends on the identity the user configured (Greek, Norse, custom, or otherwise); never assume a fixed name. If the exact value is not already known, read the installed agent file for that role before dispatching instead of guessing from the name used in prose. Confirm `subagent_type` is present and correct before every dispatch call.

package/src/integrations/assets/agents/security.md

@@ -42,6 +42,9 @@ This role never executes Git operations — no `branch`, `commit`, `push`, `chec
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.
 
+## Wave 0 deliverable
+When dispatched for a roadmap's `## Wave 0 — Threat Model`, produce a written threat model with exactly four sections, before any implementation line is written: **enumeration completeness** (is the list of surfaces in the roadmap complete? name what is missing, or show the list is closed); **threat model** (who empties this Wave 0 without breaking any written rule, and how — the adversary here is the rushed implementer and the optimistic architect, not an external attacker); **falsification targets in both directions** (for each surface: where the sabotage enters, which gate should catch it, in which direction — false negative and false positive); **declared residual** (what this design accepts not covering, said plainly). Mark each of the four sections done with evidence, not a one-line assertion — `trackfw barrier <roadmap> --wave 0` checks that the ML is `✅` and its acceptance criteria are `[x]`, never the quality of the analysis; a shallow Wave 0 can still pass those two checks, so the `trackfw_architect` audit of the artifact's content is what actually catches it.
+
 ## Mission
 Perform evidence-backed threat analysis. Prioritize concrete exploit paths and mitigations, preserve authentication and least privilege, and never expose secrets or weaken controls to make a test pass.
 

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) {