trackfw 6.0.0 → 6.3.0

package/README.md

@@ -248,6 +248,32 @@ governance_mode: strict   # CI fails on any violation
 # governance_mode: lenient # CI passes with warnings only
 ```
 
+### `update` and `sync` configuration fields
+
+`trackfw update` and `trackfw sync` read the following keys, flat at the root of `trackfw.yaml`, through
+the same loader used by every other command. All default to an empty string when absent.
+
+```yaml
+# trackfw.yaml — consumed by `trackfw update`
+hooks: husky          # husky | lefthook | native | "" (no hooks regenerated)
+ci: github             # github | gitlab | "" (no CI workflow regenerated)
+backend: node          # backend stack — informs CLAUDE.md/agent stack sections and hook commands
+frontend: react         # frontend stack — same as backend
+pkg_manager: npm        # npm | yarn | pnpm | ... — composes build/test commands in generated hooks
+
+# trackfw.yaml — consumed by `trackfw sync` (checked before the matching env var, same order in all 3 CLIs)
+linear_api_key: ""
+linear_team_id: ""
+jira_base_url: ""
+jira_email: ""
+jira_token: ""
+jira_project: ""
+```
+
+Full contract, including per-field consumers and the intentional exception for generated Git hooks
+(which read `roadmap_dir` with their own `grep`/`sed`, since they run without the `trackfw` binary
+present): `docs/cli-parity.md` → `## trackfw update vs trackfw update harness`.
+
 ---
 
 ## REQ-driven ADR discovery

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "6.0.0",
+  "version": "6.3.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, and Amazon Q.",
   "keywords": [
     "cli",
@@ -58,7 +58,8 @@
   },
   "dependencies": {
     "commander": "^12.0.0",
-    "@inquirer/prompts": "^5.0.0"
+    "@inquirer/prompts": "^5.0.0",
+    "yaml": "^2.9.0"
   },
   "engines": {
     "node": ">=18"

package/src/commands/status.js

@@ -6,7 +6,7 @@ const { t } = require('../i18n')
 const cmd = new Command('status')
 cmd.description(t('status.description'))
 cmd.action(async () => {
-  console.log(await getStatus())
+  process.stdout.write(await getStatus())
 })
 
 module.exports = cmd

package/src/commands/sync.js

@@ -5,38 +5,24 @@ const https = require('https')
 const http = require('http')
 const fs = require('fs')
 const path = require('path')
+const projectConfig = require('../config')
 
 // ---------------------------------------------------------------------------
 // Config helpers
 // ---------------------------------------------------------------------------
 
 /**
- * Lê um campo de trackfw.yaml (parse linha a linha, sem dependências externas).
- * @param {string} field
+ * Lê um campo de cfg.sync (namespace resolvido pelo carregador único, ../config —
+ * ver ADR-2026-08-02-caminho-unico-de-leitura-do-trackfw-yaml-com-namespaces-tipados.md),
+ * com fallback para variável de ambiente. Substitui o antigo scanner artesanal
+ * readConfigField (parse linha a linha de trackfw.yaml).
+ * @param {string} syncKey chave camelCase em cfg.sync (ex.: "linearApiKey")
+ * @param {string} envVar
  * @returns {string}
  */
-function readConfigField(field) {
-  try {
-    const data = fs.readFileSync('trackfw.yaml', 'utf8')
-    const prefix = field + ':'
-    for (const line of data.split('\n')) {
-      const trimmed = line.trimStart()
-      if (trimmed.startsWith(prefix)) {
-        let value = trimmed.slice(prefix.length).trim()
-        if (value.length >= 2 &&
-          ((value[0] === '"' && value[value.length - 1] === '"') ||
-           (value[0] === "'" && value[value.length - 1] === "'"))) {
-          value = value.slice(1, -1)
-        }
-        return value
-      }
-    }
-  } catch (_) { /* sem arquivo */ }
-  return ''
-}
-
-function getConfig(field, envVar) {
-  return readConfigField(field) || process.env[envVar] || ''
+function getConfig(syncKey, envVar) {
+  const cfg = projectConfig.load(process.cwd())
+  return cfg.sync[syncKey] || process.env[envVar] || ''
 }
 
 // ---------------------------------------------------------------------------
@@ -296,18 +282,18 @@ async function syncToProvider(createFn, issueField) {
 }
 
 async function syncToLinear() {
-  const apiKey = getConfig('linear_api_key', 'LINEAR_API_KEY')
-  const teamId = getConfig('linear_team_id', 'LINEAR_TEAM_ID')
+  const apiKey = getConfig('linearApiKey', 'LINEAR_API_KEY')
+  const teamId = getConfig('linearTeamId', 'LINEAR_TEAM_ID')
   if (!apiKey) throw new Error('Linear API key not found. Set LINEAR_API_KEY env var or linear_api_key in trackfw.yaml')
   if (!teamId) throw new Error('Linear Team ID not found. Set LINEAR_TEAM_ID env var or linear_team_id in trackfw.yaml')
   return syncToProvider((title, desc) => linearCreateIssue(apiKey, teamId, title, desc), 'linear_issue')
 }
 
 async function syncToJira() {
-  const baseUrl = getConfig('jira_base_url', 'JIRA_BASE_URL')
-  const email = getConfig('jira_email', 'JIRA_EMAIL')
-  const token = getConfig('jira_token', 'JIRA_TOKEN')
-  const project = getConfig('jira_project', 'JIRA_PROJECT')
+  const baseUrl = getConfig('jiraBaseUrl', 'JIRA_BASE_URL')
+  const email = getConfig('jiraEmail', 'JIRA_EMAIL')
+  const token = getConfig('jiraToken', 'JIRA_TOKEN')
+  const project = getConfig('jiraProject', 'JIRA_PROJECT')
   if (!baseUrl) throw new Error('Jira base URL not found. Set JIRA_BASE_URL env var or jira_base_url in trackfw.yaml')
   if (!email) throw new Error('Jira email not found. Set JIRA_EMAIL env var or jira_email in trackfw.yaml')
   if (!token) throw new Error('Jira API token not found. Set JIRA_TOKEN env var or jira_token in trackfw.yaml')

package/src/commands/update.js

@@ -5,6 +5,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const identityStore = require('../identity');
+const projectConfig = require('../config');
 const { runFileTarget, validateTargets, buildDocument, humanReport, silenceConsole } = require('../lib/update-engine');
 
 // `trackfw update` is project-scoped only — see docs/cli-parity.md,
@@ -12,23 +13,20 @@ const { runFileTarget, validateTargets, buildDocument, humanReport, silenceConso
 // state (~/.claude, ~/.codex, etc.). Global artifacts moved to
 // `trackfw update harness` (update-harness.js).
 
-function readUpdateConfig(rootDir) {
-  const yaml = path.join(rootDir, 'trackfw.yaml');
-  if (!fs.existsSync(yaml)) return {};
-  const lines = fs.readFileSync(yaml, 'utf8').split('\n');
-  const cfg = {};
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed.startsWith('#')) continue;
-    const idx = trimmed.indexOf(':');
-    if (idx < 0) continue;
-    const key = trimmed.slice(0, idx).trim();
-    let val = trimmed.slice(idx + 1).trim();
-    const ci = val.indexOf(' #');
-    if (ci >= 0) val = val.slice(0, ci).trim();
-    cfg[key] = val;
-  }
-  return cfg;
+// loadUpdateConfig replaces the former artisanal line-by-line scanner (readUpdateConfig) with
+// the single config loader (../config, see ADR-2026-08-02-caminho-unico-de-leitura-do-trackfw-
+// yaml-com-namespaces-tipados.md). Returns the same snake_case shape the rest of this file
+// already consumes (cfg.hooks, cfg.ci, cfg.backend, cfg.frontend, cfg.pkg_manager) so downstream
+// code (updateHooksSurgical, buildProjectTargets) needs no further change.
+function loadUpdateConfig(rootDir) {
+  const u = projectConfig.load(rootDir).update;
+  return {
+    hooks: u.hooks,
+    ci: u.ci,
+    backend: u.backend,
+    frontend: u.frontend,
+    pkg_manager: u.pkgManager,
+  };
 }
 
 function updateHooksSurgical(cfg, rootDir) {
@@ -164,7 +162,7 @@ function buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing
     // discover.js's writeValidateScript, which produces a different
     // (simpler, non-per-backend) script and made every `update` re-run
     // report "updated" against a project actually already current
-    // (ML-6H fix). readUpdateConfig returns raw trackfw.yaml keys
+    // (ML-6H fix). loadUpdateConfig returns raw trackfw.yaml keys
     // (snake_case, e.g. "pkg_manager"); buildValidateScript expects the
     // camelCase shape used by the rest of the init generators.
     apply: (root) => generators.generateValidateScript({
@@ -252,7 +250,7 @@ cmd.action((mode, options) => {
     process.exit(1);
   }
 
-  const cfg = readUpdateConfig(cwd);
+  const cfg = loadUpdateConfig(cwd);
   const dryRun = Boolean(options.dryRun);
   const installMissing = Boolean(options.installMissing);
 

package/src/config/index.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { parseDocument, isScalar, isAlias, isSeq, isMap } = require('yaml');
 
 function expandPath(filePath) {
   if (!filePath || typeof filePath !== 'string') return filePath;
@@ -38,6 +39,24 @@ function defaults() {
       roadmap: ['Roadmap:'],
     },
     acceptanceMarkers: ['## Acceptance Criteria', '## Critérios de Aceite'],
+    // ML-1A namespaces — see ADR-2026-08-02-caminho-unico-de-leitura-do-trackfw-yaml-com-
+    // namespaces-tipados.md. Keys stay flat at the YAML root; these are memory-only groupings
+    // populated by the same single parse() below, not a second read of trackfw.yaml.
+    update: {
+      hooks: '',
+      ci: '',
+      backend: '',
+      frontend: '',
+      pkgManager: '',
+    },
+    sync: {
+      linearApiKey: '',
+      linearTeamId: '',
+      jiraBaseUrl: '',
+      jiraEmail: '',
+      jiraToken: '',
+      jiraProject: '',
+    },
     rules: {
       wip_has_req:          'error',
       wip_acceptance:       'error',
@@ -48,19 +67,30 @@ function defaults() {
       folder_status:        'warning',
       filename_uniqueness:  'error',
       blocked_by_draft_adr: 'error',
+      adr_accepted_when_req_done: 'error',
     },
   };
 }
 
 let _instance = null;
 
+// MALFORMED_CONFIG_MESSAGE is written to stderr, verbatim, when trackfw.yaml exists but fails to
+// parse as YAML. Kept identical, character-for-character, to Go's MalformedConfigMessage and
+// Python's MALFORMED_CONFIG_MESSAGE — see the comment on parse() below for why the text is
+// static rather than built from the underlying library's error.
+const MALFORMED_CONFIG_MESSAGE = 'trackfw: erro ao carregar "trackfw.yaml": YAML malformado. Corrija a sintaxe do arquivo antes de continuar.';
+
 function load(cwd) {
   if (_instance) return _instance;
   _instance = defaults();
   const yamlPath = path.join(cwd || process.cwd(), 'trackfw.yaml');
   if (!fs.existsSync(yamlPath)) return _instance;
   const content = fs.readFileSync(yamlPath, 'utf8');
-  parse(content, _instance);
+  const malformed = parse(content, _instance);
+  if (malformed) {
+    process.stderr.write(MALFORMED_CONFIG_MESSAGE + '\n');
+    process.exit(1);
+  }
   return _instance;
 }
 
@@ -68,147 +98,180 @@ function reset() {
   _instance = null;
 }
 
-function parse(content, cfg) {
-  const lines = content.split('\n');
-
-  // estados existentes
-  let inAdrDirs = false;
-  let inAgents = false;
-  let adrDirs = [];
-  let agents = [];
-
-  // NOVOS estados
-  let inLinkFields = false;
-  let inLinkFieldsReq = false;
-  let inLinkFieldsAdr = false;
-  let inLinkFieldsRoadmap = false;
-  let linkFieldsReq = [];
-  let linkFieldsAdr = [];
-  let linkFieldsRoadmap = [];
-
-  let inAcceptanceMarkers = false;
-  let acceptanceMarkers = [];
-
-  let inRules = false;
-  let rules = {};
-
-  function flushBlocks() {
-    if (inAdrDirs && adrDirs.length) cfg.adrDirs = adrDirs.map(expandPath);
-    if (inAgents && agents.length) cfg.agents = agents;
-    if (inLinkFields) {
-      if (inLinkFieldsReq && linkFieldsReq.length) cfg.linkFields.req = linkFieldsReq;
-      if (inLinkFieldsAdr && linkFieldsAdr.length) cfg.linkFields.adr = linkFieldsAdr;
-      if (inLinkFieldsRoadmap && linkFieldsRoadmap.length) cfg.linkFields.roadmap = linkFieldsRoadmap;
+// resolveAlias segue a cadeia de um Alias (b: *x) até o nó âncora. Ler .source direto de um
+// Alias não resolvido devolveria o NOME da âncora, não o valor — risco confirmado no ML-0A.
+//
+// state (opcional) é marcado como { unresolved: true } quando node.resolve(doc) devolve
+// undefined — caso de uma âncora referenciada antes de ser definida (b: *x / a: &x 3), que a
+// spec YAML trata como inválido. gopkg.in/yaml.v3 e PyYAML rejeitam esse arquivo (yaml.v3:
+// "unknown anchor 'x' referenced"; PyYAML: ComposerError "found undefined alias"); a lib `yaml`
+// do Node não popula doc.errors para isso — resolve() simplesmente devolve undefined em tempo
+// de leitura. Sem este sinalizador, o valor viraria string vazia em silêncio (divergência de
+// exit code encontrada na auditoria cruzada do ML-1B); com ele, parse() devolve malformado=true
+// e load() converge com Go/Python.
+function resolveAlias(doc, node, state) {
+  let n = node;
+  while (isAlias(n)) {
+    const resolved = n.resolve(doc);
+    if (resolved === undefined) {
+      if (state) state.unresolved = true;
+      return null;
     }
-    if (inAcceptanceMarkers && acceptanceMarkers.length) cfg.acceptanceMarkers = acceptanceMarkers;
-    if (inRules && Object.keys(rules).length) Object.assign(cfg.rules, rules);
-    // reset
-    inAdrDirs = false; adrDirs = [];
-    inAgents = false; agents = [];
-    inLinkFields = false;
-    inLinkFieldsReq = false; inLinkFieldsAdr = false; inLinkFieldsRoadmap = false;
-    linkFieldsReq = []; linkFieldsAdr = []; linkFieldsRoadmap = [];
-    inAcceptanceMarkers = false; acceptanceMarkers = [];
-    inRules = false; rules = {};
+    n = resolved;
   }
+  return n;
+}
 
-  for (const rawLine of lines) {
-    const line = rawLine.trim();
-    if (!line) continue;
-    const hasIndent = rawLine.length > 0 && (rawLine[0] === ' ' || rawLine[0] === '\t');
-
-    if (!hasIndent) {
-      flushBlocks();
+// normalizeNode converte um nó da árvore `yaml` (Scalar/Seq/Map/Alias) para uma string
+// (escalar, usando o texto bruto pré-coerção via Scalar.source), um array de strings
+// (sequência) ou um objeto plano (mapeamento) — recursivamente.
+//
+// Scalar.source já devolve o texto correto tanto para escalares "plain" (não processados —
+// preserva "yes", "010", "2026-08-02" como estão no arquivo) quanto para escalares quoted/bloco
+// (já des-escapados, iguais ao .value) — confirmado empiricamente no ML-1A: não há necessidade
+// de tratar quoted e plain de formas diferentes.
+function normalizeNode(doc, node, state) {
+  const n = resolveAlias(doc, node, state);
+  if (n == null) return '';
+  if (isScalar(n)) {
+    return n.source != null ? n.source : (n.value == null ? '' : String(n.value));
+  }
+  if (isSeq(n)) {
+    return n.items.map((item) => normalizeNode(doc, item, state));
+  }
+  if (isMap(n)) {
+    const result = {};
+    for (const pair of n.items) {
+      const key = resolveAlias(doc, pair.key, state);
+      const keyStr = isScalar(key) ? (key.source != null ? key.source : String(key.value)) : String(key);
+      result[keyStr] = normalizeNode(doc, pair.value, state);
     }
+    return result;
+  }
+  return '';
+}
 
-    if (hasIndent) {
-      if (inAdrDirs) {
-        if (line.startsWith('- ')) {
-          let val = line.slice(2).trim();
-          val = val.replace(/^["']|["']$/g, '');
-          adrDirs.push(expandPath(val));
-        }
-        continue;
-      }
-      if (inAgents) {
-        if (line.startsWith('- ')) agents.push(line.slice(2).trim());
-        continue;
-      }
-      if (inAcceptanceMarkers) {
-        if (line.startsWith('- ')) {
-          let val = line.slice(2).trim();
-          val = val.replace(/^["']|["']$/g, '');
-          acceptanceMarkers.push(val);
-        }
-        continue;
-      }
-      if (inRules) {
-        const colonIdx = line.indexOf(':');
-        if (colonIdx > 0) {
-          const k = line.slice(0, colonIdx).trim();
-          const v = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
-          if (k) rules[k] = v;
-        }
-        continue;
-      }
-      if (inLinkFields) {
-        if (line.startsWith('- ')) {
-          let val = line.slice(2).trim();
-          val = val.replace(/^["']|["']$/g, '');
-          if (inLinkFieldsReq) linkFieldsReq.push(val);
-          else if (inLinkFieldsAdr) linkFieldsAdr.push(val);
-          else if (inLinkFieldsRoadmap) linkFieldsRoadmap.push(val);
-        } else {
-          // sub-chave dentro de link_fields
-          const colonIdx = line.indexOf(':');
-          const subKey = colonIdx > 0 ? line.slice(0, colonIdx).trim() : line.replace(':', '').trim();
-          // flush sub-campo anterior
-          if (inLinkFieldsReq && linkFieldsReq.length) { cfg.linkFields.req = linkFieldsReq; linkFieldsReq = []; }
-          if (inLinkFieldsAdr && linkFieldsAdr.length) { cfg.linkFields.adr = linkFieldsAdr; linkFieldsAdr = []; }
-          if (inLinkFieldsRoadmap && linkFieldsRoadmap.length) { cfg.linkFields.roadmap = linkFieldsRoadmap; linkFieldsRoadmap = []; }
-          inLinkFieldsReq = false; inLinkFieldsAdr = false; inLinkFieldsRoadmap = false;
-          if (subKey === 'req') inLinkFieldsReq = true;
-          else if (subKey === 'adr') inLinkFieldsAdr = true;
-          else if (subKey === 'roadmap') inLinkFieldsRoadmap = true;
-        }
-        continue;
-      }
-      continue;
-    }
+function stringVal(m, key) {
+  const v = m[key];
+  return typeof v === 'string' ? v : undefined;
+}
 
-    // linha top-level
-    const colonIdx = line.indexOf(':');
-    if (colonIdx < 0) continue;
-    const key = line.slice(0, colonIdx).trim();
-    const val = line.slice(colonIdx + 1).trim();
-    if (!key) continue;
-
-    switch (key) {
-      case 'adr_dirs':              inAdrDirs = true; adrDirs = []; break;
-      case 'req_dir':               cfg.reqDir = expandPath(val.replace(/^["']|["']$/g, '')); break;
-      case 'roadmap_dir':           cfg.roadmapDir = expandPath(val.replace(/^["']|["']$/g, '')); break;
-      case 'roadmap_namespacing':   cfg.roadmapNamespacing = val; break;
-      case 'agents':                inAgents = true; agents = []; break;
-      case 'governance_mode':       cfg.governanceMode = val; break;
-      case 'lenient_until':         cfg.lenientUntil = val; break;
-      case 'wip_limit':             { const n = parseInt(val, 10); if (n > 0) cfg.wipLimit = n; break; }
-      case 'wip_by_squad':          cfg.wipBySquad = val === 'true'; break;
-      case 'stale_wip_days':        { const n = parseInt(val, 10); if (n > 0) cfg.staleWipDays = n; break; }
-      case 'require_req_in_commit': cfg.requireReqInCommit = val === 'true'; break;
-      case 'strict_ci_paths':       cfg.strictCiPaths = val === 'true'; break;
-      case 'trace_id_field':        cfg.traceIdField = val.replace(/^["']|["']$/g, ''); break;
-      case 'forge':                 cfg.forge = val.replace(/^["']|["']$/g, ''); break;
-      case 'link_fields':           inLinkFields = true; break;
-      case 'acceptance_markers':    inAcceptanceMarkers = true; acceptanceMarkers = []; break;
-      case 'rules':                 inRules = true; rules = {}; break;
+// stringList converte um valor normalizado (array) em array de strings. Uma sequência
+// presente-porém-vazia devolve array vazio (não undefined), distinguindo "presente e vazio" de
+// "ausente" — contrato herdado do fix de lista inline.
+function stringList(v) {
+  if (!Array.isArray(v)) return undefined;
+  return v.filter((item) => typeof item === 'string');
+}
+
+// NON_FATAL_ERROR_CODES holds `yaml` package error codes that must NOT trigger the fatal path,
+// because gopkg.in/yaml.v3 (decoding into a generic Node, not a struct) and PyYAML's
+// yaml.compose() silently accept the same input — divergence found by ML-1B audit: a
+// "wip_limit: 3\nwip_limit: 4\n" duplicate-key file made Node exit 1 while Go and Python both
+// parsed it fine (both resolve to "last key wins", same value trackfw ends up using in all
+// three once DUPLICATE_KEY is excluded here). Only Node's `yaml` treats duplicate keys as a
+// composer-level error; treating it as fatal here would make the fatal trigger itself diverge
+// across CLIs, which is exactly the defect this ML exists to avoid. Any other doc.errors entry
+// (e.g. BAD_INDENT — an actually-unparseable document) still triggers the fatal path below.
+const NON_FATAL_ERROR_CODES = new Set(['DUPLICATE_KEY']);
+
+// parse applies the ~20 known keys from content onto cfg. Returns true when content is
+// malformed YAML (the caller, load(), turns that into a fatal stderr message + exit 1) and
+// false otherwise — including the benign cases of an absent/empty/comments-only document
+// (doc.contents === null with no errors) or a document whose top-level node parses fine but
+// isn't a mapping (valid YAML, unexpected shape): neither of those is a parse failure, so both
+// stay silent no-ops, same as before this function grew an error signal.
+//
+// The `yaml` package doesn't throw on syntax errors — parseDocument() always returns a Document,
+// and populates doc.errors instead (a passive failure channel). The try/catch below is kept as
+// defense-in-depth for library versions/inputs that do throw, but the actual malformed-YAML path
+// exercised by trackfw.yaml goes through the doc.errors.length > 0 check.
+function parse(content, cfg) {
+  let doc;
+  try {
+    doc = parseDocument(content);
+  } catch (e) {
+    return true;
+  }
+  if (doc && doc.errors && doc.errors.some((e) => !NON_FATAL_ERROR_CODES.has(e.code))) return true;
+  if (!doc || !doc.contents) return false;
+  if (!isMap(doc.contents)) return false;
+
+  const state = { unresolved: false };
+  const m = normalizeNode(doc, doc.contents, state);
+  if (state.unresolved) return true;
+  if (typeof m !== 'object' || m === null || Array.isArray(m)) return false;
+
+  if (m.adr_dirs !== undefined) {
+    const items = stringList(m.adr_dirs);
+    if (items) cfg.adrDirs = items.map(expandPath);
+  }
+  if (stringVal(m, 'req_dir') !== undefined) cfg.reqDir = expandPath(m.req_dir);
+  if (stringVal(m, 'roadmap_dir') !== undefined) cfg.roadmapDir = expandPath(m.roadmap_dir);
+  if (stringVal(m, 'roadmap_namespacing') !== undefined) cfg.roadmapNamespacing = m.roadmap_namespacing;
+  if (m.agents !== undefined) {
+    const items = stringList(m.agents);
+    if (items) cfg.agents = items;
+  }
+  if (stringVal(m, 'governance_mode') !== undefined) cfg.governanceMode = m.governance_mode;
+  if (stringVal(m, 'lenient_until') !== undefined) cfg.lenientUntil = m.lenient_until;
+  if (stringVal(m, 'wip_limit') !== undefined) {
+    const n = parseInt(m.wip_limit, 10);
+    if (n > 0) cfg.wipLimit = n;
+  }
+  if (stringVal(m, 'wip_by_squad') !== undefined) cfg.wipBySquad = m.wip_by_squad === 'true';
+  if (stringVal(m, 'stale_wip_days') !== undefined) {
+    const n = parseInt(m.stale_wip_days, 10);
+    if (n > 0) cfg.staleWipDays = n;
+  }
+  if (stringVal(m, 'require_req_in_commit') !== undefined) cfg.requireReqInCommit = m.require_req_in_commit === 'true';
+  if (stringVal(m, 'strict_ci_paths') !== undefined) cfg.strictCiPaths = m.strict_ci_paths === 'true';
+  if (stringVal(m, 'trace_id_field') !== undefined) cfg.traceIdField = m.trace_id_field;
+  if (stringVal(m, 'forge') !== undefined) cfg.forge = m.forge;
+  if (m.acceptance_markers !== undefined) {
+    const items = stringList(m.acceptance_markers);
+    if (items) cfg.acceptanceMarkers = items;
+  }
+  if (m.link_fields !== undefined && typeof m.link_fields === 'object' && !Array.isArray(m.link_fields)) {
+    const lf = m.link_fields;
+    const req = stringList(lf.req);
+    if (req) cfg.linkFields.req = req;
+    const adr = stringList(lf.adr);
+    if (adr) cfg.linkFields.adr = adr;
+    const roadmap = stringList(lf.roadmap);
+    if (roadmap) cfg.linkFields.roadmap = roadmap;
+  }
+  if (m.rules !== undefined && typeof m.rules === 'object' && !Array.isArray(m.rules)) {
+    for (const [k, v] of Object.entries(m.rules)) {
+      if (typeof v === 'string') cfg.rules[k] = v;
     }
   }
 
-  // flush final (EOF)
-  flushBlocks();
+  // ML-1A — update and sync namespaces. Same normalized `m` as above, no second read.
+  if (stringVal(m, 'hooks') !== undefined) cfg.update.hooks = m.hooks;
+  if (stringVal(m, 'ci') !== undefined) cfg.update.ci = m.ci;
+  if (stringVal(m, 'backend') !== undefined) cfg.update.backend = m.backend;
+  if (stringVal(m, 'frontend') !== undefined) cfg.update.frontend = m.frontend;
+  if (stringVal(m, 'pkg_manager') !== undefined) cfg.update.pkgManager = m.pkg_manager;
+  if (stringVal(m, 'linear_api_key') !== undefined) cfg.sync.linearApiKey = m.linear_api_key;
+  if (stringVal(m, 'linear_team_id') !== undefined) cfg.sync.linearTeamId = m.linear_team_id;
+  if (stringVal(m, 'jira_base_url') !== undefined) cfg.sync.jiraBaseUrl = m.jira_base_url;
+  if (stringVal(m, 'jira_email') !== undefined) cfg.sync.jiraEmail = m.jira_email;
+  if (stringVal(m, 'jira_token') !== undefined) cfg.sync.jiraToken = m.jira_token;
+  if (stringVal(m, 'jira_project') !== undefined) cfg.sync.jiraProject = m.jira_project;
+
+  return false;
 }
 
 const NAMESPACING_FLAT = 'flat';
 const NAMESPACING_BY_AGENT = 'by_agent';
 
-module.exports = { load, reset, defaults, expandPath, NAMESPACING_FLAT, NAMESPACING_BY_AGENT };
+module.exports = {
+  load,
+  reset,
+  defaults,
+  expandPath,
+  NAMESPACING_FLAT,
+  NAMESPACING_BY_AGENT,
+  MALFORMED_CONFIG_MESSAGE,
+};

package/src/generators/roadmap.js

@@ -419,10 +419,12 @@ function newRoadmap(title, reqPath) {
   const filename = `${backlogDir}/ROADMAP-${date}-${slug}.md`
   fs.mkdirSync(backlogDir, { recursive: true })
 
+  const reqField = reqPath ? `"${reqPath}"` : '""'
+
   const body = `---
 status: backlog
 date: ${date}
-req: ""
+req: ${reqField}
 squad: ""
 ---
 
@@ -434,6 +436,11 @@ squad: ""
 <!-- What problem does this roadmap solve? Link the REQ. -->
 REQ: ${reqPath || ''}
 
+## Acceptance Criteria
+<!-- Consolidated criteria for this roadmap. Detail per ML in the waves below. -->
+- [ ]
+- [ ]
+
 ## Wave 1 — <name> (parallel MLs)
 > Dependencies: none
 
@@ -509,7 +516,7 @@ function newRoadmapFromReq(reqPath) {
   const body = `---
 status: backlog
 date: ${date}
-req: "${basename}"
+req: "${reqPath}"
 squad: ""
 ---
 
@@ -521,6 +528,11 @@ squad: ""
 <!-- Derived from REQ: ${basename} -->
 REQ: ${reqPath}${adrRef}
 
+## Acceptance Criteria
+<!-- Consolidated criteria for this roadmap. Detail per ML in the waves below. -->
+- [ ]
+- [ ]
+
 ${mlSection}
 `