trackfw 7.3.0 → 7.4.0

package/src/generators/hooks.js

@@ -3,6 +3,7 @@
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
+const { homedir } = require('../homedir')
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -143,8 +144,8 @@ if command -v jq &>/dev/null; then
   TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
   MSG=$(echo "$INPUT" | jq -r '(.tool_input.question // .tool_input.command // "Agent is executing: \\(.tool_name // "unknown")") | .[0:300]')
 else
-  TOOL=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name',''))" 2>/dev/null || echo "")
-  MSG=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); ti=d.get('tool_input',{}); print((ti.get('question') or ti.get('command') or 'Agent is executing: '+d.get('tool_name','unknown'))[:300])" 2>/dev/null || echo "Agent needs attention")
+  TOOL=$(echo "$INPUT" | PYTHONIOENCODING=utf-8 python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name',''))" 2>/dev/null || echo "")
+  MSG=$(echo "$INPUT" | PYTHONIOENCODING=utf-8 python3 -c "import sys,json; d=json.load(sys.stdin); ti=d.get('tool_input',{}); print((ti.get('question') or ti.get('command') or 'Agent is executing: '+d.get('tool_name','unknown'))[:300])" 2>/dev/null || echo "Agent needs attention")
 fi
 
 ROADMAP_DIR=$(grep '^roadmap_dir:' trackfw.yaml 2>/dev/null | head -1 | sed 's/^roadmap_dir:[[:space:]]*//; s/[[:space:]]*#.*$//' | tr -d '"' | tr -d "'" || true)
@@ -1257,14 +1258,14 @@ const GBG_CMD_WINDSURF = 'bash scripts/trackfw-git-branch-guard.sh'
 
 /** Mirrors Go's globalCredentialGuardScriptPath. */
 function globalCredentialGuardScriptPath() {
-  const home = os.homedir()
+  const home = homedir()
   if (!home) return null
   return path.join(home, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
 }
 
 /** Reads+parses JSON at $HOME/<...relParts>; returns null on any failure (fail-open). */
 function readGlobalHookJSON(...relParts) {
-  const home = os.homedir()
+  const home = homedir()
   if (!home) return null
   try {
     const raw = fs.readFileSync(path.join(home, ...relParts), 'utf8')
@@ -1290,9 +1291,121 @@ function readGlobalHookJSON(...relParts) {
  * (normalizeGuardPath) and pypi/trackfw/generators/hooks.py
  * (_normalize_guard_path). Never call with anything other than a script
  * path -- it is not a general string normalizer.
+ *
+ * ROADMAP-2026-09-03 ML-7B -- Windows separator canonicalization, gated on
+ * anchoring, NOT a blanket "\\" -> "/" translate. On POSIX "\\" is a legal
+ * filename byte, so translating it unconditionally would make two
+ * genuinely different paths (one with a literal backslash in a segment
+ * name, one with an extra path separator there) compare equal -- the exact
+ * dangerous loosening this function's own doc comment warns against, and
+ * the risk this ML was told to treat explicitly. The decision, per input
+ * shape (mirrors the UNC/drive-letter arms of
+ * internal/validator/pathIsAnchoredForHookConfig (Go) / index.js's
+ * pathIsAnchoredForHookConfig, reimplemented locally -- not imported,
+ * different question, and this module must not import the validator):
+ *
+ *   - "C:\Users\x\guard.sh" / "C:/Users/x/guard.sh" (ASCII drive letter,
+ *     ":", then "\" or "/") -- CANONICALIZED: every "\" is translated to
+ *     "/" before the collapse below runs, so both forms land on the same
+ *     "C:/Users/x/guard.sh". This is the case ML-7A measured as the actual
+ *     trigger (a path.join-computed Windows path vs. a hand-concatenated
+ *     one).
+ *   - "\\servidor\share\guard.sh" (valid UNC: non-empty SERVER not "." or
+ *     "..", followed by a non-empty SHARE not itself starting with "\") --
+ *     UNCHANGED, byte-for-byte, including its backslashes. Translating it
+ *     would collapse "\\server\share" into "//server/share" and then this
+ *     function's own "//" -> "/" collapse would eat the second slash,
+ *     producing "/server/share/..." -- indistinguishable from a
+ *     single-leading-backslash, drive-root-relative path
+ *     ("\server\share\..." means something else on Windows) or from a
+ *     same-named POSIX path. That collision is precisely a false "already
+ *     installed": a network-share guard would dedup-match a local one.
+ *     Left untouched, a UNC command never cross-matches a non-UNC one -- no
+ *     new equality is introduced.
+ *   - "//servidor/share/guard.sh" (the POSIX-typed equivalent of UNC) --
+ *     UNCHANGED behavior from before this ML: it does not start with "\",
+ *     so it never enters the new branch above; it still collapses via the
+ *     existing "//" -> "/" rule below, same as any other POSIX path. Not
+ *     unified with the "\\servidor\share\..." form above (pre-existing
+ *     asymmetry, out of scope for this ML).
+ *   - "\\" and "\\x" alone (no SHARE segment) -- NOT valid UNC by the
+ *     predicate above, so they fall through unchanged: no drive letter, no
+ *     valid UNC, no translation.
+ *   - "C:foo" (drive-relative, no separator after ":") and homoglyph/
+ *     zero-width-prefixed strings (e.g. "\uFF43:\...", "\u200bC:\...") --
+ *     do NOT match the ASCII-only, position-0 drive-letter check, so no
+ *     translation happens. Same anti-spoofing posture as the validator's
+ *     drive-letter check.
+ *
+ * Known residual, documented not fixed (hades-tf ML-7B barrier review,
+ * 2026-09-05 parecer): three real Windows-with-"\" shapes have no drive
+ * letter at position 0, so hasWindowsDriveLetterPrefix's gate leaves them
+ * uncanonicalized -- the same pre-ML-7A defect survives for them. Direction
+ * is always TIGHTENS (possible duplicate hook entry), never loosens (the
+ * guard is never silently skipped) -- same safe direction as every other
+ * case above:
+ *
+ *   - "\\?\C:\Users\x\guard.sh" (the Win32 long-path prefix; a real form
+ *     Windows/long-path APIs produce automatically, not a hypothetical).
+ *   - A relative path containing "\" (e.g. "guard\scripts\hook.sh"). Low
+ *     practical risk: today both sides of the real comparison always come
+ *     from path.join with an absolute home, so a relative command should
+ *     not reach this function -- but nothing in the comparator itself
+ *     prevents it.
+ *   - A home resolved via a network-profile UNC path (e.g.
+ *     "\\fileserver\homes\kg\.trackfw\scripts\..."). It never enters the
+ *     drive-letter branch and is intentionally left untouched (see the UNC
+ *     bullet above), so the original defect persists for both UNC
+ *     spellings, not just between UNC and drive-letter forms.
+ *
+ * Not fixed here on purpose: closing any of the three would touch the
+ * drive-letter gate this barrier just approved as conservative, trading a
+ * duplicate-entry nuisance for the more expensive failure mode (collapsing
+ * genuinely different paths into a false "already installed"). Do not treat
+ * rediscovering these three as a new finding.
+ */
+/**
+ * Reports whether p begins with a Windows UNC prefix ("\\server\share...")
+ * with a non-empty SERVER segment (not "." or "..") followed by a non-empty
+ * SHARE segment that does not itself start with another backslash. Mirrors
+ * the UNC arm of index.js's pathIsAnchoredForHookConfig -- reimplemented
+ * here (not imported: different question, and this module must not import
+ * the validator). "\\", "\\x" (no share segment) and "\\.\x" / "\\..\evil"
+ * (server "." or "..") are NOT valid UNC. Currently unused by
+ * normalizeGuardPath itself (a valid-UNC string never has a drive-letter
+ * prefix, so the two checks are already mutually exclusive by construction)
+ * -- kept as a named, tested predicate so the "UNC stays untouched"
+ * decision above is verifiable by name, not just by absence of a call, same
+ * as Go's hasValidUNCPrefix (internal/generators/agentfiles.go) and
+ * Python's _has_valid_unc_prefix (pypi/trackfw/generators/hooks.py).
+ * EXPORTED (unlike Go's package-private equivalent) only because
+ * npm/tests/guard_path_normalize.test.js reaches it via
+ * require('../src/generators/hooks') destructuring -- there is no
+ * production caller. Do not build new logic against this export assuming
+ * UNC gets active handling; it does not (see the doc comment above).
  */
+function hasValidUNCPrefix(p) {
+  if (p.length < 2 || p[0] !== '\\' || p[1] !== '\\') return false
+  const rest = p.slice(2)
+  const cut = rest.indexOf('\\')
+  if (cut === -1) return false
+  const server = rest.slice(0, cut)
+  const share = rest.slice(cut + 1)
+  return server !== '' && server !== '.' && server !== '..' && share !== '' && share[0] !== '\\'
+}
+
+function hasWindowsDriveLetterPrefix(p) {
+  if (p.length < 3) return false
+  const c = p.charCodeAt(0)
+  const isASCIILetter = (c >= 97 && c <= 122) || (c >= 65 && c <= 90)
+  return isASCIILetter && p[1] === ':' && (p[2] === '\\' || p[2] === '/')
+}
+
 function normalizeGuardPath(p) {
   if (!p) return p
+  if (hasWindowsDriveLetterPrefix(p)) {
+    p = p.split('\\').join('/')
+  }
   let out = ''
   let prevSlash = false
   for (const ch of p) {
@@ -1410,7 +1523,7 @@ function globalCredentialGuardInstalledCopilot() {
  * explicit instruction for Kiro.
  */
 function globalCredentialGuardInstalledKiro() {
-  const home = os.homedir()
+  const home = homedir()
   if (!home) return false
   try {
     const stat = fs.statSync(path.join(home, '.kiro', 'hooks', 'trackfw-credential-guard.json'))
@@ -1437,7 +1550,7 @@ function globalCredentialGuardInstalledKiro() {
 
 /** Mirrors Go's globalGitBranchGuardScriptPath. */
 function globalGitBranchGuardScriptPath() {
-  const home = os.homedir()
+  const home = homedir()
   if (!home) return null
   return path.join(home, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
 }
@@ -2264,6 +2377,8 @@ module.exports = {
   mergeCopilotHookArray,
   normalizeGuardPath,
   samePathCommand,
+  hasValidUNCPrefix,
+  hasWindowsDriveLetterPrefix,
   // Template constants — exported for scaffold doctor (ADR-2026-08-27).
   // These are the single source of truth for each script's content; the
   // scaffold doctor compares on-disk files against these exact bytes, using

package/src/generators/init.js

@@ -4,6 +4,17 @@ const fs = require('fs')
 const path = require('path')
 const os = require('os')
 const { readAgentConventions } = require('../config/index.js')
+const { homedir } = require('../homedir');
+
+// PACKAGE_VERSION — the version of the trackfw binary generating the CI
+// workflow templates. Read once from package.json (never a literal), so
+// the pin written into the workflow always tracks the generator that
+// wrote it (ADR-2026-08-28: gate de CI nasce pinado na versão que o
+// gerou). Reused by buildGitHubActionsWorkflowContent /
+// buildGitLabCIWorkflowContent AND by scaffold doctor's comparison
+// (which calls the same functions), so drift between write and compare
+// paths is structurally impossible.
+const { version: PACKAGE_VERSION } = require('../../package.json')
 
 const GOV_DIRS = [
   'docs/adr',
@@ -31,6 +42,7 @@ async function scaffold(cfg, cwd) {
   }
 
   generateVaultIndex(root)
+  generateGitAttributes(root)
   writeTrackfwConfig(cfg, root)
   generateValidateScript(cfg, root)
   generateAttentionScripts(cfg, root)
@@ -45,6 +57,60 @@ async function scaffold(cfg, cwd) {
   injectHooksDetected(root)
 }
 
+// gitAttributesRuleTarget — primeiro campo da regra mantida por este gerador.
+// Casa o BASENAME (padrão sem barra) de propósito: `roadmap_dir` e `req_dir` são
+// configuráveis por projeto (trackfw.yaml) e ambos carregam um `.trackfw-log`,
+// então caminho fixo nasceria quebrado em quem configurou diretório diferente.
+const GITATTRIBUTES_RULE_TARGET = '.trackfw-log'
+
+// GITATTRIBUTES_BLOCK — byte-idêntico ao de internal/generators/scaffold.go e
+// pypi/trackfw/generators/init_gen.py (regra dura de paridade).
+const GITATTRIBUTES_BLOCK = `# trackfw: .trackfw-log is append-only — every write lands on the last line, so
+# two parallel branches conflict on every merge. merge=union keeps the lines
+# from both sides (chronological order is not guaranteed). The pattern has no
+# slash, so it matches the file in any directory — roadmap_dir and req_dir both
+# carry one, and both are configurable per project.
+.trackfw-log merge=union
+`
+
+/**
+ * hasGitAttributesRule — verdadeiro quando ALGUMA linha não-comentário tem
+ * `.trackfw-log` como primeiro campo. Predicado sobre o CAMPO, não sobre a
+ * string literal da linha inteira: espaçamento diferente ou outro atributo já
+ * são "a regra existe", e reescrever por cima sobrescreveria decisão do projeto.
+ * @param {string} content
+ */
+function hasGitAttributesRule(content) {
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) continue
+    if (trimmed.split(/\s+/)[0] === GITATTRIBUTES_RULE_TARGET) return true
+  }
+  return false
+}
+
+/**
+ * generateGitAttributes — garante `merge=union` para o `.trackfw-log` no
+ * `.gitattributes` da raiz. Três ramos, todos idempotentes: ausente → cria;
+ * existe sem a regra → APPEND (nunca sobrescreve); existe com a regra → no-op.
+ * @param {string} root
+ */
+function generateGitAttributes(root) {
+  const filePath = path.join(root || process.cwd(), '.gitattributes')
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, GITATTRIBUTES_BLOCK, 'utf8')
+    console.log('  ✓ .gitattributes')
+    return
+  }
+  const existing = fs.readFileSync(filePath, 'utf8')
+  if (hasGitAttributesRule(existing)) return
+  // Arquivo preexistente sem newline final: emendar direto grudaria a primeira
+  // linha do bloco na última linha do projeto, corrompendo a config em silêncio.
+  const prefix = existing !== '' && !existing.endsWith('\n') ? existing + '\n' : existing
+  fs.writeFileSync(filePath, prefix + GITATTRIBUTES_BLOCK, 'utf8')
+  console.log('  ✓ .gitattributes')
+}
+
 /**
  * generateVaultIndex — cria vault/notes/index.md se ainda não existir.
  * @param {string} root
@@ -209,7 +275,18 @@ function generateCIWorkflow(cfg) {
 // workflow generator would write. Exported for scaffold doctor (ADR-2026-08-27): the
 // comparison uses the same function the write path uses, so drift is structurally impossible.
 // The cfg parameter is accepted for API symmetry with Go's buildGitHubActionsWorkflowContent
-// (which also ignores cfg for now — the template is not cfg-dependent).
+// (which also ignores cfg for now — the template is cfg-independent but, since
+// ADR-2026-08-28, NOT version-independent: it pins TRACKFW_VERSION to the version of the
+// trackfw binary that generated it, read from package.json — never a literal).
+//
+// Job id is `governance-install-script` (ML-1A, ROADMAP-2026-09-01): was `governance`,
+// colliding with the discover-installed sibling workflow's job id (trackfw-validate.yml,
+// buildDiscoverGitHubActionsWorkflowContent in commands/discover.js) — both previously
+// `governance`, producing two identically-named check-runs on any PR of a project with
+// both workflows installed, which makes required_status_checks ambiguous (GitHub
+// matches by name). Named after the install mechanism (install.sh here, `go install`
+// there) rather than the workflow file, since that's what a required_status_checks
+// reader needs to tell the two apart without opening the YAML.
 function buildGitHubActionsWorkflowContent(_cfg) {
   return `name: trackfw-gate
 on:
@@ -217,8 +294,11 @@ on:
     branches: [main]
 
 jobs:
-  governance:
+  governance-install-script:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      TRACKFW_VERSION: "${PACKAGE_VERSION}"
     steps:
       - uses: actions/checkout@v4
 
@@ -232,11 +312,15 @@ jobs:
 }
 
 // buildGitLabCIWorkflowContent mirrors buildGitHubActionsWorkflowContent for GitLab CI.
+// Same version-pin rationale as above — see buildGitHubActionsWorkflowContent.
 function buildGitLabCIWorkflowContent(_cfg) {
   return `# trackfw governance gate
 trackfw-gate:
   stage: test
   image: alpine:latest
+  timeout: 10 minutes
+  variables:
+    TRACKFW_VERSION: "${PACKAGE_VERSION}"
   before_script:
     - apk add --no-cache curl
     - curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
@@ -333,9 +417,12 @@ function generateCommitMsgHook(cfg) {
 // ---------------------------------------------------------------------------
 
 function generatePomXml(cfg) {
-  const slug = cfg.projectName
-    ? cfg.projectName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '')
-    : 'my-app'
+  // Usa o toSlug compartilhado em vez de uma variante inline: a versao anterior nao
+  // fazia NFKD e PERDIA a letra acentuada — "Cafe App" (com acento) virava "caf-app"
+  // aqui e "cafe-app" no Go, que usa o toSlug dele. Ver a secao
+  // "Artifact slug contract" em docs/cli-parity.md.
+  const { toSlug } = require('./adr')
+  const slug = cfg.projectName ? toSlug(cfg.projectName) : 'my-app'
   const name = cfg.projectName || 'My App'
   const content = `<?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
@@ -789,6 +876,13 @@ function backendCommands(cfg) {
 // (missing roadmap.md, implement.md, barrier.md) undetected.
 // ---------------------------------------------------------------------------
 
+// CLAUDE_COMMANDS "trackfw não está instalado" blurbs (AC13) are deliberately
+// OUT of the version pin introduced by ADR-2026-08-28. This text is shown when
+// the `trackfw` command fails because it is not installed — recommending the
+// exact old version that generated the project would be worse UX than
+// pointing at `releases/latest`, since the reason to (re)install is usually
+// being outdated. Do not pin these on a future pass without a product
+// decision; see ROADMAP-2026-08-28 Wave 0 §3 (AC13 row).
 const CLAUDE_COMMANDS = {
     'adr.md': `Execute o seguinte comando bash: \`trackfw adr new "$ARGUMENTS"\`
 
@@ -1304,7 +1398,7 @@ async function installAmazonQ(cwd = process.cwd()) {
 async function installIntegrationTarget(target, cwd = process.cwd(), scope = 'project', { onSkip } = {}) {
   const { execute, buildPlans } = require('../integrations')
   const { resolveAgentModels } = require('../config')
-  const { models: agentModels, warning: agentModelsWarning } = resolveAgentModels(scope, os.homedir(), cwd)
+  const { models: agentModels, warning: agentModelsWarning } = resolveAgentModels(scope, homedir(), cwd)
   if (agentModelsWarning) process.stderr.write(agentModelsWarning + '\n')
   const roots = { projectRoot: cwd }
   const options = { targets: [target], scope, onSkip, agentModels }
@@ -1340,7 +1434,7 @@ function generateClaudeCommandsForce(rootDir) {
  * installSkillsForce — sobrescreve ~/.claude/skills/trackfw/SKILL.md sempre.
  */
 function installSkillsForce() {
-  const skillDir = path.join(os.homedir(), '.claude', 'skills', 'trackfw')
+  const skillDir = path.join(homedir(), '.claude', 'skills', 'trackfw')
   fs.mkdirSync(skillDir, { recursive: true })
 
   const content = `---
@@ -1418,6 +1512,8 @@ module.exports = {
   generateClaudeCommands,
   generateClaudeCommandsForce,
   generateVaultIndex,
+  generateGitAttributes,
+  GITATTRIBUTES_BLOCK,
   installSkillsForce,
   installAgents,
   installGemini,

package/src/generators/req.js

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