trackfw 7.3.0 → 7.5.0

package/README.md

@@ -18,6 +18,13 @@ ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned
 
 Every piece of work traces back to a decision. Every decision links to a requirement. Every requirement lands in a roadmap. No orphan work, no undocumented choices.
 
+> 🚧 **Platform support: Linux and macOS are supported. Windows support is partial.**
+> The CLIs install on Windows and core governance commands run — but the generated
+> guard hooks are POSIX shell scripts, and **on several agent CLIs they do not execute
+> on Windows.** They are written to disk and reported as installed while never running.
+> Native Windows hooks are in progress.
+> **Read [Windows support (partial)](#windows-support-partial) before adopting on Windows.**
+
 ---
 
 ## The problem
@@ -93,9 +100,68 @@ npm install -g trackfw
 ```
 
 The npm package is pure Node.js — no compiled binary or postinstall download.
-It works wherever Node.js ≥ 18 is installed. Shared behavior, including the AI
+It installs wherever Node.js ≥ 18 is installed. Shared behavior, including the AI
 integration lifecycle, follows the [CLI parity contract](docs/cli-parity.md).
 
+> **The CLI installs on Node ≥ 18 alone — the generated guard hooks do not run on
+> Node alone.** They are POSIX shell scripts and need a POSIX shell to execute. On
+> Windows, see [Windows support](#windows-support-partial) before relying on them.
+
+### Windows support (partial)
+
+🚧 **Windows support is partial and in progress. Read this before adopting `trackfw`
+on Windows.**
+
+We publish a Windows binary and the npm/pip packages install on Windows. That is not
+the same as the tool working end to end, and we would rather tell you where the edges
+are than let you find them after adoption.
+
+**What we know works**
+
+- The three CLIs install (`npm install -g trackfw`, `pip install trackfw`, and the
+  published `trackfw_<version>_windows_amd64.tar.gz`).
+- Core governance commands — `req new`, `roadmap new`, `roadmap move`, `status`,
+  `validate` — run, and artifacts are written with LF endings.
+
+**What we know does not work yet**
+
+- `scripts/install.sh` **refuses Windows**, even though we publish a Windows binary.
+  Install manually from the release archive for now.
+- Our Windows CI still reports **known test failures**. They are mapped by root cause,
+  not unknown — but they are not zero.
+- **Windows ARM64 is not built.** Only `windows_amd64` is published.
+
+**Guard hooks on Windows — measured, per agent CLI**
+
+The guard hooks are `.sh` scripts, executed by *your* AI agent CLI. Which shell that CLI
+uses on Windows decides whether they run at all. We measured it:
+
+| Agent CLI | Shell on Windows | Do the hooks run? | Basis |
+|---|---|---|---|
+| Gemini CLI | PowerShell, always | ❌ **No** | measured in vendor source |
+| Codex CLI | PowerShell on the normal path | ❌ **No** | measured in vendor source |
+| GitHub Copilot CLI | — | ❌ **No** — we populate the wrong config field | vendor docs + our code |
+| Claude Code | Git Bash if installed, else PowerShell | ⚠️ **Only with Git Bash** | vendor documentation |
+| Cursor · Kiro | unknown | ❓ **Unknown** | closed, undocumented |
+
+🔴 **This is the failure mode we care most about, because it is silent.** A guard that
+never executes still reports health over something it never inspected. On the CLIs marked
+❌, `trackfw validate` will tell you the hook is installed — and it will never fire.
+
+**Until native Windows hooks ship, do not rely on `credential_guard` or
+`git_branch_guard` as an enforced control on Windows.** Treat them as documentation of
+intent, not as enforcement.
+
+We are **not** going to answer this by requiring Git Bash: it would fix one CLI out of
+six and push the cost onto you. Windows hooks should run on Windows. Native hook
+generation is the direction — see
+[`docs/portabilidade/2026-09-05-contrato-de-execucao-de-hook-por-cli-de-agente-no-windows.md`](docs/portabilidade/2026-09-05-contrato-de-execucao-de-hook-por-cli-de-agente-no-windows.md)
+for the full measurement, per CLI, with the level of certainty of each row.
+
+**If you are on Windows**, we want your report. The Windows defects fixed so far came
+from a user running the tool on real Windows 11 and measuring before reporting — open
+an issue with what you measured.
+
 ### pip
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "7.3.0",
+  "version": "7.5.0",
   "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, Amazon Q, OpenCode, and Kiro.",
   "keywords": [
     "cli",

package/src/commands/adr.js

@@ -6,6 +6,7 @@ const { Command } = require('commander')
 const { input } = require('@inquirer/prompts')
 const generators = require('../generators/adr')
 const { t } = require('../i18n')
+const { homedir } = require('../homedir')
 
 const cmd = new Command('adr')
 cmd.description(t('adr.description'))
@@ -19,7 +20,7 @@ cmd.description(t('adr.description'))
  */
 function resolveAdrDir(scope) {
   if (scope === 'global') {
-    return path.join(os.homedir(), '.trackfw', 'adr')
+    return path.join(homedir(), '.trackfw', 'adr')
   }
   if (scope === 'project') {
     return require('../config').load().adrDirs[0]

package/src/commands/barrier.js

@@ -103,11 +103,201 @@ function findWave(lines, waveLabel, roadmapBasename) {
   return { startLine: wave.startLine, endLine: wave.endLine }
 }
 
+// CRITERIA_HEADER_RE accepts both the canonical English header (ADR
+// 2026-08-29 decision 1) and the Portuguese one, which remains accepted with
+// no removal date (decision 2 — 99/143 roadmaps in the corpus use it,
+// including artifacts in done/). The `^` anchor is load-bearing: an
+// unanchored match would casar dentro de prosa ou de cerca de código, turning
+// a quoted literal into forged acceptance evidence.
+const CRITERIA_HEADER_RE = /^\*\*(?:Acceptance criteria|Crit[ée]rios de aceite):\*\*/
+
+// STATUS_VOCABULARY is the closed set of first-token markers recognised as
+// "complete" (ADR decision 3): the checkmark emoji, and the English/Portuguese
+// words, matched after case-folding and diacritics-folding. Deliberately
+// closed and explicit — "feito", "ok", "finalizado" are out (ADR, Alternatives
+// Considered — "accept any non-empty status" is the rejected no-op design).
+const STATUS_VOCABULARY = new Set(['✅', 'done', 'concluido'])
+
+// VS16 is the single variation selector this module treats as cosmetic
+// noise: the one emoji keyboards insert after "checkmark" to force
+// text-style presentation (ADR 2026-08-29 decision 9, exception clause). No
+// other variation selector or combining mark gets this treatment.
+const VS16 = '\u{FE0F}'
+
+// stripVS16 removes only U+FE0F occurrences from token. Deliberately
+// narrower than "strip every variation selector" or "strip every Mn": VS16
+// is the one documented cosmetic exception (ADR decision 9); anything else
+// of category Mn is now a rejection, not a fold (see
+// hasDisallowedCombiningMark).
+function stripVS16(token) {
+  return token.split(VS16).join('')
+}
+
+// hasDisallowedCombiningMark reports whether token (with VS16 already
+// removed) contains any Unicode category Mn (Mark, Nonspacing) codepoint.
+// ADR 2026-08-29 decision 9: after the single VS16 exception, any combining
+// mark on the first status token is rejected outright \u2014 the ML is NOT
+// complete \u2014 rather than folded away. A vocabulary this small exists to
+// refuse ambiguity; silently folding combining marks reopens exactly the
+// ambiguity it exists to close ("d<U+1DC0>one" must not read as "done").
+//
+// ORDER IS LOAD-BEARING: this check MUST run on the token BEFORE NFD
+// decomposition, not after. "Conclu\u00eddo" in its authored (NFC) form has
+// no literal Mn codepoint \u2014 the accented "\u00ed" is a single
+// precomposed codepoint. NFD-decomposing it *produces* a trailing Mn
+// (U+0301, COMBINING ACUTE ACCENT) that normalizeStatusToken then strips
+// for vocabulary matching. Running this rejection check on the
+// already-decomposed string would treat that legitimate,
+// vocabulary-sanctioned accent the same as an injected combining mark and
+// reject "Conclu\u00eddo" outright, breaking AC15's own positive case.
+// Checking the raw, pre-decomposition token instead lets it through here
+// (no literal Mn present) while still catching a combining mark authored
+// directly onto the token, which is category Mn in either form, decomposed
+// or not.
+function hasDisallowedCombiningMark(token) {
+  return /\p{Mn}/u.test(token)
+}
+
+// normalizeStatusToken folds diacritics and lower-cases the token for
+// vocabulary comparison. Uses the \p{Mn} Unicode property escape (General
+// Category "Mark, Nonspacing") instead of a hand-enumerated code point range,
+// to match Go's runes.In(unicode.Mn) and Python's unicodedata.category(ch) \u2014
+// all three fold every combining mark that survives to this point, which,
+// after hasDisallowedCombiningMark has already run, only happens as a
+// byproduct of NFD-decomposing an accented Latin letter (e.g. "Conclu\u00eddo"
+// -> "Concluido"). Callers MUST have already rejected via
+// hasDisallowedCombiningMark before calling this \u2014 see that function's
+// doc comment for why.
+function normalizeStatusToken(token) {
+  return token.normalize('NFD').replace(/\p{Mn}/gu, '').toLowerCase()
+}
+
+// statusIsComplete implements rule 3 by FIRST TOKEN, not substring (ADR
+// decision 3, AC8/AC9/AC14). marker is the already-trimmed remainder of the
+// "**Status:**" line. Splitting on /\s+/ treats U+00A0 (NBSP) as a separator \u2014
+// matching the accepted "NBSP separator" case \u2014 while a zero-width character
+// (U+200B, not matched by \s) stays glued to the token and safely causes
+// rejection (a usability false-negative, not a security concern).
+//
+// This is the fix for vault/notes/adr-status-substring-livre-falso-positivo-2026-08-01.md:
+// `marker.includes('checkmark')` would classify "**Status:** [pending] checkmark" as
+// complete (reproduced live against 7.3.0 \u2014 ADR decision 8). First-token
+// comparison rejects it because the first token is the pending glyph, not the marker.
+//
+// ADR decision 9: VS16 is stripped first (the one cosmetic exception), then
+// any remaining combining mark on the raw token rejects outright \u2014 see
+// hasDisallowedCombiningMark for why this must happen before NFD.
+function statusIsComplete(marker) {
+  const trimmed = marker.trim()
+  if (trimmed.length === 0) return false
+  const first = stripVS16(trimmed.split(/\s+/)[0])
+  if (hasDisallowedCombiningMark(first)) return false
+  return STATUS_VOCABULARY.has(normalizeStatusToken(first))
+}
+
+// splitRoadmapLines is the single boundary where the raw file content becomes
+// the array every marker regex operates on. It normalizes CRLF line endings
+// by stripping a trailing "\r" from each line produced by splitting on
+// "\n" — every downstream marker (ML heading, "**Status:**", acceptance
+// header, criterion lines, "**Gates da wave:**", the fence delimiter) then
+// sees the same content it would see for an LF-only file. It does NOT handle
+// a lone-CR (old-Mac-style) file: splitting on "\n" alone leaves such a file
+// as one giant line, same as internal/commands/barrier.go's splitRoadmapLines.
+// Python's universal-newlines read does handle lone CR — a known, accepted
+// asymmetry; issue #216 (the defect motivating this fix) is CRLF specifically.
+//
+// Unlike Go and Python, this runtime DOES depend on this normalization: JS
+// regex "." excludes "\r" (it is a LineTerminator per the ECMAScript spec,
+// unlike Go's RE2 "."), so `/^\*\*Status:\*\*(.*)$/.exec("**Status:** done\r")`
+// returns null — a CRLF roadmap with every ML fully completed was reported as
+// "not complete (status: missing)" (mirrors internal/commands/barrier.go
+// splitRoadmapLines and the universal-newline read in
+// pypi/trackfw/commands/barrier.py).
+//
+// Only the trailing "\r" immediately before the split point is stripped —
+// this must never be confused with per-line indentation trimming, which
+// ML-1B deliberately removed: leading whitespace on a marker line still fails
+// to match (markers are anchored at column 0, untouched by this function).
+function splitRoadmapLines(content) {
+  return content.split('\n').map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line))
+}
+
+// detectFenceMarker inspects a whitespace-trimmed line and reports whether it
+// opens or closes a CommonMark-style fence: a run of 3+ identical backtick
+// (`) or tilde (~) characters at the start of the line. Returns
+// { char, length } or null. ADR decision (ML-1B, achado 1): CommonMark
+// defines a fence as 3+ of the SAME character (backtick or tilde), closed by
+// a run of the same character with length >= the opening run — masking only
+// "```" left both "~~~" fences and 4+-backtick fences (whose interior can
+// nest a 3-backtick block) unmasked, which is the escape route a hostile
+// roadmap would use.
+function detectFenceMarker(trimmed) {
+  if (trimmed.length === 0) return null
+  const first = trimmed[0]
+  if (first !== '`' && first !== '~') return null
+  let i = 0
+  while (i < trimmed.length && trimmed[i] === first) i++
+  if (i < 3) return null
+  return { char: first, length: i }
+}
+
+// computeFenceMask returns, for each line index, whether that line lies
+// strictly inside a fenced code block (``` ... ``` or ~~~ ... ~~~, per
+// CommonMark: 3+ of the same fence character, closed by a run of the same
+// character with length >= the opening run's length). A line that is itself
+// a fence delimiter is never reported as "inside" — only the lines between an
+// opening and a closing delimiter are masked. ADR decision 7 / AC13: ML
+// detection, status and acceptance-header parsing must ignore documentation/
+// examples inside a cerca — otherwise a roadmap that cites those literals (as
+// this very roadmap, its REQ and its ADR do, repeatedly) is read as real ML
+// content. parseGates already has its own, independent fence-matching for the
+// "```bash ... ```" gates block and is untouched by this mask.
+function computeFenceMask(lines) {
+  const mask = new Array(lines.length).fill(false)
+  let fenced = false
+  let fenceChar = null
+  let fenceLen = 0
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim()
+    const marker = detectFenceMarker(trimmed)
+    if (!fenced) {
+      if (marker) {
+        fenced = true
+        fenceChar = marker.char
+        fenceLen = marker.length
+        continue
+      }
+      continue
+    }
+    // Currently inside a fence: only a marker of the SAME character with
+    // length >= the opening run closes it (a nested shorter/different
+    // marker stays masked as interior content) — AND, per CommonMark, a
+    // closing fence line contains NOTHING besides the fence run and
+    // (already-trimmed) surrounding whitespace: marker.length === trimmed.length.
+    // Fix for hades-tf security review (2026-08-29, achado #1 /
+    // vault/notes/barrier-fence-closing-trailing-content-bypass-2026-08-29.md):
+    // a line like "```trailing-junk" found INSIDE an open fence does not
+    // close it in real CommonMark — it stays interior content — but the
+    // prior check treated any run of length >= fenceLen as a valid close
+    // regardless of trailing text. The opening branch above is unchanged:
+    // CommonMark allows an info string after the opening run (` ```bash `).
+    if (marker && marker.char === fenceChar && marker.length >= fenceLen && marker.length === trimmed.length) {
+      fenced = false
+      continue
+    }
+    mask[i] = true
+  }
+  return mask
+}
+
 // findMLs locates every `### ML-` heading inside [startLine, endLine) and returns
-// { id, lines } for each, where `lines` is the ML body (heading excluded).
-function findMLs(lines, startLine, endLine) {
+// { id, lines, fenced } for each, where `lines` is the ML body (heading excluded)
+// and `fenced` is the fence mask aligned to `lines`. fenceMask defaults to "no
+// fences" so existing call sites that omit it keep working (ML-1A, AC13).
+function findMLs(lines, startLine, endLine, fenceMask = computeFenceMask(lines)) {
   const headings = []
   for (let i = startLine; i < endLine; i++) {
+    if (fenceMask[i]) continue
     if (/^### ML-/.test(lines[i])) {
       const m = /^### (\S+)/.exec(lines[i])
       headings.push({ id: m[1], headingLine: i })
@@ -116,57 +306,104 @@ function findMLs(lines, startLine, endLine) {
   return headings.map((h, idx) => {
     let end = endLine
     for (let j = h.headingLine + 1; j < endLine; j++) {
+      if (fenceMask[j]) continue
       if (/^### /.test(lines[j]) || /^## /.test(lines[j])) { end = j; break }
     }
-    return { id: h.id, lines: lines.slice(h.headingLine + 1, end) }
+    return {
+      id: h.id,
+      lines: lines.slice(h.headingLine + 1, end),
+      fenced: fenceMask.slice(h.headingLine + 1, end),
+    }
   })
 }
 
-// mlCompletionStatus applies rule 3 — completion is a `**Status:**` line whose
-// remainder contains ✅. Returns { complete, marker } where marker is "missing"
-// when no `**Status:**` line exists at all.
-function mlCompletionStatus(mlLines) {
-  for (const raw of mlLines) {
-    const line = raw.trim()
-    const m = /^\*\*Status:\*\*(.*)$/.exec(line)
+// mlCompletionStatus applies rule 3 — completion is by FIRST TOKEN (ADR
+// decision 3), not substring. Returns { complete, marker } where marker is
+// "missing" when no `**Status:**` line exists at all. Lines inside a fenced
+// code block are ignored (ADR decision 7, AC13-a) — `fenced` is aligned to
+// `mlLines`. Matched against the RAW line (no per-line .trim()) — an indented
+// marker does not count (ML-1B, achado 2): Go and Python already require
+// column 0 via `^` against the untrimmed line, and Node's prior .trim() made
+// it the only runtime that released a wave on indented markers.
+//
+// Default omitted on purpose (hades-tf security review, 2026-08-29, achado
+// #3 / hefesto-tf): a `fenced = []` default left every `fenced[i]` as
+// `undefined` when the caller forgot the argument — indistinguishable from
+// "nothing is fenced", silently turning OFF the fence-masking protection this
+// very function exists to enforce. Production call sites always pass
+// `ml.fenced` (never exploitable today), but a completion gate must fail
+// CLOSED on a missing argument, not open. The default below marks every line
+// as fenced (masked) instead, so an accidentally omitted argument yields
+// "missing"/not-complete rather than "everything counts as real content".
+function mlCompletionStatus(mlLines, fenced = mlLines.map(() => true)) {
+  for (let i = 0; i < mlLines.length; i++) {
+    if (fenced[i]) continue
+    const m = /^\*\*Status:\*\*(.*)$/.exec(mlLines[i])
     if (m) {
       const marker = m[1].trim()
-      return { complete: marker.includes('✅'), marker: marker.length > 0 ? marker : 'missing' }
+      return { complete: statusIsComplete(marker), marker: marker.length > 0 ? marker : 'missing' }
     }
   }
   return { complete: false, marker: 'missing' }
 }
 
 // mlAcceptanceEvidence applies rule 4. Returns { hasBlock, total, unmet }.
-function mlAcceptanceEvidence(mlLines) {
+// Lines inside a fenced code block are ignored throughout — for the header
+// search, for the "**" block-end boundary, and for counting criterion lines —
+// otherwise a cerca citing the acceptance header/`- [x]` as an example would
+// forge acceptance evidence (ADR decision 7, AC13-a). All markers are matched
+// against the RAW line (no per-line .trim()) — an indented marker does not
+// count (ML-1B, achado 2): Go and Python already require column 0 via `^`
+// against the untrimmed line, and Node's prior .trim() made it the only
+// runtime that released a wave on indented markers.
+//
+// Default omitted on purpose — same rationale as mlCompletionStatus above
+// (hades-tf security review, 2026-08-29, achado #3 / hefesto-tf): fail
+// CLOSED (every line treated as fenced/masked, so `hasBlock: false` and no
+// forged criteria are counted) if the caller omits `fenced`, instead of
+// silently disabling the fence mask.
+function mlAcceptanceEvidence(mlLines, fenced = mlLines.map(() => true)) {
   let blockStart = -1
   for (let i = 0; i < mlLines.length; i++) {
-    if (/^\*\*Crit[ée]rios de aceite:\*\*/.test(mlLines[i].trim())) { blockStart = i; break }
+    if (fenced[i]) continue
+    if (CRITERIA_HEADER_RE.test(mlLines[i])) { blockStart = i; break }
   }
   if (blockStart === -1) return { hasBlock: false, total: 0, unmet: 0 }
 
   let blockEnd = mlLines.length
   for (let j = blockStart + 1; j < mlLines.length; j++) {
-    if (/^\*\*/.test(mlLines[j].trim())) { blockEnd = j; break }
+    if (fenced[j]) continue
+    if (/^\*\*/.test(mlLines[j])) { blockEnd = j; break }
   }
 
-  const blockLines = mlLines.slice(blockStart + 1, blockEnd)
-    .map(l => l.trim())
-    .filter(l => l.length > 0)
-
-  const criteria = blockLines.filter(l => /^- \[/.test(l))
+  const criteria = []
+  for (let i = blockStart + 1; i < blockEnd; i++) {
+    if (fenced[i]) continue
+    const l = mlLines[i]
+    if (/^- \[.\]/.test(l)) criteria.push(l)
+  }
   if (criteria.length === 0) return { hasBlock: false, total: 0, unmet: 0 }
 
   const unmet = criteria.filter(l => /^- \[ \]/.test(l))
   return { hasBlock: true, total: criteria.length, unmet: unmet.length }
 }
 
+// GATES_HEADER_RE mirrors Go's gatesHeaderRe / Python's _GATES_HEADER_RE: a
+// PREFIX match at column 0, not full-line equality — a header followed by
+// trailing prose/whitespace on the same line ("**Gates da wave:** (obrigatórios)")
+// or a CRLF-terminated line ("**Gates da wave:**\r") must still be recognised,
+// exactly as Go/Python already do.
+const GATES_HEADER_RE = /^\*\*Gates da wave:\*\*/
+
 // parseGates applies rule 5. Returns { commands }. Throws UsageError naming the
-// offending line number for an unterminated fence.
+// offending line number for an unterminated fence. The header marker is
+// matched against the RAW line (no per-line .trim()) — an indented
+// '**Gates da wave:**' does not count (ML-1B, achado 2): Go and Python
+// already require column 0 for this marker.
 function parseGates(lines, startLine, endLine) {
   let markerLine = -1
   for (let i = startLine; i < endLine; i++) {
-    if (lines[i].trim() === '**Gates da wave:**') { markerLine = i; break }
+    if (GATES_HEADER_RE.test(lines[i])) { markerLine = i; break }
   }
   if (markerLine === -1) return { commands: [] }
 
@@ -200,7 +437,7 @@ function evalMlsComplete(mls, waveLabel) {
   const evidence = []
   const failures = []
   for (const ml of mls) {
-    const { complete, marker } = mlCompletionStatus(ml.lines)
+    const { complete, marker } = mlCompletionStatus(ml.lines, ml.fenced)
     if (complete) evidence.push(`${ml.id}: ✅`)
     else failures.push(`${ml.id}: not complete (status: ${marker})`)
   }
@@ -214,7 +451,7 @@ function evalAcceptanceEvidence(mls) {
   const evidence = []
   const failures = []
   for (const ml of mls) {
-    const ev = mlAcceptanceEvidence(ml.lines)
+    const ev = mlAcceptanceEvidence(ml.lines, ml.fenced)
     if (!ev.hasBlock) {
       failures.push(`${ml.id}: no acceptance block`)
     } else if (ev.unmet > 0) {
@@ -304,6 +541,13 @@ function roadmapTrustForGates(roadmapPath) {
   return { trusted: true }
 }
 
+// SH_MISSING_MSG is the pinned failure string for a `gates` check that could not
+// be evaluated because `sh` is not on $PATH (AC3, AC4). All three runtimes (Go,
+// Node, Python) must emit this byte-for-byte — see docs/cli-parity.md
+// "Pinned failure strings for not_evaluated".
+const SH_MISSING_MSG =
+  'gates not evaluated: sh not found in PATH — install a POSIX shell (e.g. Git Bash, WSL) to evaluate gates'
+
 function evalGates(commands, cwd, trustResult = { trusted: true }) {
   // trustResult: { trusted: true } | { trusted: false, failureMsg: string }
   if (!trustResult.trusted) {
@@ -320,12 +564,31 @@ function evalGates(commands, cwd, trustResult = { trusted: true }) {
   const evidence = []
   const failures = []
   for (const command of commands) {
-    const result = spawnSync(command, {
-      shell: true,
+    // `sh` is invoked explicitly, as argv[0], and resolved through $PATH — NOT
+    // spawnSync's `shell: true`, which is pinned to a fixed /bin/sh. This is the
+    // same $PATH resolution Go has always used via exec.LookPath, and it is
+    // required for Windows: the Git Bash `sh.exe` is never at /bin/sh and is
+    // only reachable via $PATH.
+    const result = spawnSync('sh', ['-c', command], {
       cwd,
       encoding: 'utf8',
       stdio: 'pipe',
     })
+    if (result.error) {
+      // The process never started at all (e.g. `sh` missing from $PATH) —
+      // distinct from the gate command itself failing inside a running `sh`,
+      // which surfaces as a normal exit code (e.g. 127 for "tool not found")
+      // and never sets result.error. "Could not measure" is not "measured and
+      // failed" (AC3, AC4) — stop immediately: gates after this one were never
+      // observed, so they must not appear in evidence or failures.
+      return {
+        name: 'gates',
+        status: 'not_evaluated',
+        commands,
+        evidence: [],
+        failures: [SH_MISSING_MSG],
+      }
+    }
     const code = result.status === null || result.status === undefined ? 1 : result.status
     if (code === 0) evidence.push(`${command}: exit 0`)
     else failures.push(`${command}: exit ${code}`)
@@ -407,7 +670,7 @@ async function runBarrier(roadmapArg, waveOption, jsonOutput, trustLocalGates) {
   const cfg = config.load()
   const resolved = resolveRoadmapFile(cfg, roadmapArg)
   const content = fs.readFileSync(resolved.path, 'utf8')
-  const lines = content.split('\n')
+  const lines = splitRoadmapLines(content)
 
   const startedAt = new Date()
   const wave = findWave(lines, waveLabel, resolved.basename)
@@ -476,6 +739,10 @@ module.exports.findMLs = findMLs
 module.exports.mlCompletionStatus = mlCompletionStatus
 module.exports.mlAcceptanceEvidence = mlAcceptanceEvidence
 module.exports.parseGates = parseGates
+module.exports.statusIsComplete = statusIsComplete
+module.exports.computeFenceMask = computeFenceMask
+module.exports.splitRoadmapLines = splitRoadmapLines
+module.exports.CRITERIA_HEADER_RE = CRITERIA_HEADER_RE
 module.exports.roadmapTrustForGates = roadmapTrustForGates
 module.exports.evalMlsComplete = evalMlsComplete
 module.exports.evalAcceptanceEvidence = evalAcceptanceEvidence

package/src/commands/context.js

@@ -4,7 +4,7 @@ const { Command } = require('commander')
 const fs = require('fs')
 const path = require('path')
 const config = require('../config')
-const { validate } = require('../validator')
+const { validate, resolveAgentNamespaces, resolveReqFiles } = require('../validator')
 
 /**
  * extractFrontmatterField — extrai valor de campo YAML dentro de bloco --- ... ---.
@@ -85,11 +85,37 @@ function collectEntries(dir, type, state) {
   return entries
 }
 
+/**
+ * collectReqEntries — entradas de REQ para o `context`, derivadas do ponto único de leitura
+ * (resolveReqFiles). O `state` sai do nome da pasta-pai quando ela é um estado legado; em layout
+ * flat ou no canônico req_dir/<agente>/*.md não há estado (invariante D1: REQ não tem estado).
+ * @param {object} cfg
+ * @returns {Array<{type:string,file:string,status:string,state?:string}>}
+ */
+function collectReqEntries(cfg) {
+  const STATES = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']
+  const entries = []
+  for (const full of resolveReqFiles(cfg)) {
+    let content = ''
+    try { content = fs.readFileSync(full, 'utf8') } catch (_) {}
+    const parent = path.basename(path.dirname(full))
+    const state = STATES.includes(parent) ? parent : ''
+    let status = extractFrontmatterField(content, 'status')
+    if (!status) status = extractInlineStatus(content)
+    if (!status) status = state || 'unknown'
+    const entry = { type: 'REQ', file: path.basename(full), status }
+    if (state) entry.state = state
+    entries.push(entry)
+  }
+  return entries
+}
+
 /**
  * getContext — coleta governança e imprime em md ou json.
  * @param {string} format - 'md' | 'json'
+ * @returns {Promise<void>}
  */
-function getContext(format) {
+async function getContext(format) {
   const cfg = config.load()
 
   // ADRs
@@ -98,41 +124,15 @@ function getContext(format) {
     adrs.push(...collectEntries(adrDir, 'ADR'))
   }
 
-  // REQs
-  const reqs = []
-  const reqDir = cfg.reqDir || cfg.req_dir || 'docs/req'
-  const reqNamespacing = cfg.roadmapNamespacing || cfg.roadmap_namespacing || ''
-  if (reqNamespacing === 'by_agent') {
-    const STATES = ['backlog', 'wip', 'blocked', 'done', 'abandoned']
-    let agents = cfg.agents || []
-    if (!agents.length) {
-      try {
-        agents = fs.readdirSync(reqDir).filter(f => {
-          try { return fs.statSync(path.join(reqDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) {}
-    }
-    for (const agent of agents) {
-      for (const state of STATES) {
-        reqs.push(...collectEntries(path.join(reqDir, agent, state), 'REQ', state))
-      }
-    }
-  } else {
-    reqs.push(...collectEntries(reqDir, 'REQ'))
-  }
+  // REQs — pelo PONTO ÚNICO de leitura (ADR-2026-09-03, D3/D4). Antes, `context` montava a própria
+  // árvore (flat, ou <agente>/<estado>/ em by_agent) e não enxergava o layout canônico <agente>/*.md.
+  const reqs = collectReqEntries(cfg)
 
   // Roadmaps
   const roadmaps = []
   const states = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
   if (cfg.roadmapNamespacing === '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 states) {
         const dir = path.join(cfg.roadmapDir, agent, state)
@@ -147,7 +147,7 @@ function getContext(format) {
   }
 
   // Validate
-  const { violations, warnings } = validate()
+  const { violations, warnings } = await validate()
 
   // Score
   let score = 0
@@ -202,8 +202,14 @@ module.exports = (function () {
   cmd
     .description('Print governance context for LLM consumption')
     .option('--format <fmt>', 'Output format: md or json', 'md')
-    .action((opts) => {
-      getContext(opts.format)
-    })
+    // Retorna a Promise: o bin roda parseAsync() e só assim uma rejeição chega
+    // ao .catch(reportFatalError) com exit code 1 em vez de virar unhandled
+    // rejection (ML-1A, ROADMAP-2026-09-02-context-do-cli-node-aguarda-validate).
+    .action((opts) => getContext(opts.format))
   return cmd
 })()
+
+// Exposto para teste: o teste de context em by_agent duplicava a lógica de coleta e, por isso,
+// continuava verde mesmo quando a produção mudava (asserção sobre uma CÓPIA). Anexar a função ao
+// Command exportado é o menor caminho para o teste exercitar o código de produção de fato.
+module.exports.collectReqEntries = collectReqEntries