trackfw 6.1.0 → 6.3.1

package/README.md

@@ -144,7 +144,8 @@ trackfw ship -m "feat(auth): add login flow"
 | `trackfw adr new "title"` | Create a new Architecture Decision Record |
 | `trackfw adr list` | List all ADRs with status |
 | `trackfw req new "title"` | Create a REQ with guided ADR discovery |
-| `trackfw req list` | List all REQs with status |
+| `trackfw req list` | List all REQs with status, discovered across flat, per-state, and by_agent layouts |
+| `trackfw req move <name> <status>` | Update a REQ's status; physically relocates the file when it already lives in a recognized state subfolder (see [Multi-agent namespacing](#multi-agent-namespacing)) |
 | `trackfw roadmap new "title"` | Create a roadmap in `backlog/` |
 | `trackfw roadmap show <name>` | Print a roadmap with its current state |
 | `trackfw roadmap move <name> <state>` | Move roadmap between states |
@@ -210,6 +211,29 @@ agents: [claude, gemini, copilot]
 
 Artifacts are organized by agent: `docs/roadmaps/claude/wip/`, `docs/req/gemini/done/`. `trackfw validate` and `trackfw context` are fully by_agent-aware — no false positives.
 
+REQs reuse this same `roadmap_namespacing` setting — there is no separate `req_namespacing` key. When
+`by_agent` is configured, REQs may live under `req_dir/<agent>/<state>/` just like roadmaps do.
+
+`trackfw req list` and `trackfw req move` discover REQs across three layouts at once (each is a fixed,
+non-recursive glob — a REQ nested deeper than these patterns is not found), with no extra flag required:
+
+- **Flat (legacy):** `req_dir/*.md` — REQs loose directly in the REQ directory.
+- **Per-state:** `req_dir/<state>/*.md` — organized by state, without an agent segment.
+- **By agent:** `req_dir/<agent>/<state>/*.md` — used when `roadmap_namespacing: by_agent` is set.
+
+`trackfw req move <name> <status>` behaves conditionally depending on where the REQ currently lives:
+
+- If the REQ already sits inside a recognized state subfolder (per-state or by_agent layout above), the
+  move **physically relocates the file** to the target state's folder, mirroring `trackfw roadmap move` —
+  the folder is the source of truth for state. In this mode `<status>` must be one of the six governance
+  states (`backlog`, `analyzing`, `wip`, `blocked`, `done`, `abandoned`) — any other value is rejected
+  with `invalid state`.
+- If the REQ is loose in `req_dir/` (flat legacy layout), the move rewrites the `status:` frontmatter
+  field **in place** and does not move or create any folder. `<status>` is written verbatim in this
+  mode — it accepts the free-form values existing REQs already use (`Open`, `Done`, ...), not just the
+  six governance state names. Existing flat REQs are never migrated automatically — you are not forced
+  to reorganize a project's existing REQs to adopt this behavior.
+
 ### Bidirectional traceability (`trace_id_field`)
 
 ```yaml
@@ -248,6 +272,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.1.0",
+  "version": "6.3.1",
   "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/req.js

@@ -64,13 +64,18 @@ cmd.command('new <title>')
 cmd.command('list')
   .description(t('req.list.description'))
   .action(async () => {
-    listREQs(require('../config').load().reqDir)
+    listREQs(require('../config').load())
   })
 
 cmd.command('move <name> <status>')
   .description('Update a REQ status in place')
   .action(async (name, status) => {
-    moveREQ(name, status)
+    try {
+      moveREQ(name, status)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exitCode = 1
+    }
   })
 
 module.exports = cmd

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/req.js

@@ -2,27 +2,86 @@
 const fs = require('fs')
 const path = require('path')
 const { localDateISO } = require('./date')
+const roadmapGen = require('./roadmap')
+const config = require('../config')
+
+const VALID_STATES = roadmapGen.VALID_STATES
+const STATE_ORDER = roadmapGen.STATE_ORDER
 
 /**
- * listREQs — lista arquivos .md em dir, imprimindo filename e status (coluna 60 chars).
- * Extrai status da linha `> Date: ... | Status: ...`.
- * Se dir não existe ou vazio: imprime "No REQs found in <dir>".
+ * 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.
+ * @param {object} cfg — config completo (ver npm/src/config)
+ * @returns {string[]} paths completos, na ordem flat → por-estado → by_agent
  */
-function listREQs(dir) {
-  let files = []
+function listREQFiles(cfg) {
+  const reqDir = cfg.reqDir
+  const files = []
+
+  // (a) flat legado — reqDir/*.md
   try {
-    files = fs.readdirSync(dir).filter(f => f.endsWith('.md'))
-  } catch (_) {
-    // dir não existe
+    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
+}
+
+/**
+ * listREQs — lista REQs (recursivo nos 3 layouts), imprimindo filename e status (coluna 60 chars).
+ * Extrai status da linha `> Date: ... | Status: ...`.
+ * Se nenhum REQ encontrado: imprime "No REQs found in <reqDir>".
+ * @param {object} cfg — config completo (ver npm/src/config)
+ */
+function listREQs(cfg) {
+  const files = listREQFiles(cfg)
+
   if (files.length === 0) {
-    console.log(`No REQs found in ${dir}`)
+    console.log(`No REQs found in ${cfg.reqDir}`)
     return
   }
 
-  for (const filename of files) {
-    const filepath = path.join(dir, filename)
+  for (const filepath of files) {
+    const filename = path.basename(filepath)
     const status = parseREQStatus(filepath)
     console.log(`${filename.padEnd(60)} ${status}`)
   }
@@ -105,30 +164,105 @@ function rewriteREQStatus(source, status) {
   return { content: `---\n${lines.join('\n')}${rest}`, changed: true }
 }
 
-function findREQ(name, reqDir) {
-  let files = []
-  try {
-    files = fs.readdirSync(reqDir).filter(f => f.endsWith('.md'))
-  } catch (e) {
-    throw new Error(`reading REQ dir: ${e.message}`)
-  }
+/**
+ * findREQ — busca recursiva nos 3 layouts (flat → por-estado → by_agent), retornando o primeiro
+ * path cujo basename contém `name` (case-insensitive).
+ * @param {string} name
+ * @param {object} cfg — config completo (ver npm/src/config)
+ * @returns {string} path completo
+ */
+function findREQ(name, cfg) {
+  const files = listREQFiles(cfg)
   const lower = name.toLowerCase()
-  const found = files.find(f => f.toLowerCase().includes(lower))
-  if (!found) throw new Error(`REQ "${name}" not found in ${reqDir}`)
-  return path.join(reqDir, found)
+  const found = files.find(f => path.basename(f).toLowerCase().includes(lower))
+  if (!found) throw new Error(`REQ "${name}" not found in ${cfg.reqDir}`)
+  return found
 }
 
+/**
+ * appendREQTransitionLog — append em <reqDir>/.trackfw-log, mesmo formato de
+ * appendTransitionLog (roadmap.js), em arquivo de log separado (escopo de REQ, não roadmap).
+ */
+function appendREQTransitionLog(cfg, basename, fromState, toState) {
+  const now = new Date()
+  const yyyy = now.getFullYear()
+  const mm = String(now.getMonth() + 1).padStart(2, '0')
+  const dd = String(now.getDate()).padStart(2, '0')
+  const hh = String(now.getHours()).padStart(2, '0')
+  const min = String(now.getMinutes()).padStart(2, '0')
+  const timestamp = `${yyyy}-${mm}-${dd} ${hh}:${min}`
+  const line = `${timestamp}  ${basename.padEnd(50)}  ${fromState} → ${toState}\n`
+
+  try {
+    const lp = path.join(cfg.reqDir, '.trackfw-log')
+    fs.mkdirSync(path.dirname(lp), { recursive: true })
+    fs.appendFileSync(lp, line, 'utf8')
+  } catch (_) { /* best-effort, mesmo padrão do roadmap */ }
+}
+
+/**
+ * moveREQ — reescreve status: e, condicionalmente, move fisicamente o arquivo
+ * (ADR-2026-08-04, decisão D3):
+ * - REQ solta em `reqDir/` → modo in-place (comportamento legado: só reescreve status, sem mover).
+ * - REQ já organizada em `reqDir/<estado>/` ou `reqDir/<agente>/<estado>/` → move fisicamente
+ *   para o novo estado, preservando o layout (por-estado ou by_agent), e loga a transição.
+ */
 function moveREQ(name, status) {
   if (!String(status || '').trim()) throw new Error('status is required')
-  const reqDir = require('../config').load().reqDir
-  const filepath = findREQ(name, reqDir)
+  const cfg = require('../config').load()
+  const filepath = findREQ(name, cfg)
   const source = fs.readFileSync(filepath, 'utf8')
   const result = rewriteREQStatus(source, status)
   if (!result.changed) {
     throw new Error(`REQ "${path.basename(filepath)}" has no frontmatter status/header Status to update`)
   }
-  fs.writeFileSync(filepath, result.content, 'utf8')
-  console.log(`✓ updated ${path.basename(filepath)} status → ${status}`)
+
+  const basename = path.basename(filepath)
+  const parentDir = path.dirname(filepath)
+  const grandparentDir = path.dirname(parentDir)
+  const greatGrandparentDir = path.dirname(grandparentDir)
+  const reqDirAbs = path.resolve(cfg.reqDir)
+  const fromState = path.basename(parentDir)
+
+  if (path.resolve(parentDir) === reqDirAbs) {
+    // modo in-place — REQ solta em reqDir/, comportamento legado (sem mover)
+    fs.writeFileSync(filepath, result.content, 'utf8')
+    console.log(`✓ updated ${basename} status → ${status}`)
+    return
+  }
+
+  if (!VALID_STATES.includes(status)) {
+    throw new Error(`invalid state "${status}" — valid states: ${VALID_STATES.join(', ')}`)
+  }
+
+  let targetDir = null
+  let logBasename = basename
+
+  if (path.resolve(grandparentDir) === reqDirAbs && VALID_STATES.includes(fromState)) {
+    // layout por-estado — reqDir/<estado>/
+    targetDir = path.join(cfg.reqDir, status)
+  } else if (VALID_STATES.includes(fromState) && path.resolve(greatGrandparentDir) === reqDirAbs) {
+    // layout by_agent — reqDir/<agente>/<estado>/
+    const agent = path.basename(grandparentDir)
+    targetDir = path.join(cfg.reqDir, agent, status)
+    logBasename = `${agent}/${basename}`
+  }
+
+  if (!targetDir) {
+    // layout não reconhecido — fallback seguro para in-place (não inventa destino)
+    fs.writeFileSync(filepath, result.content, 'utf8')
+    console.log(`✓ updated ${basename} status → ${status}`)
+    return
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true })
+  const dst = path.join(targetDir, basename)
+  fs.writeFileSync(dst, result.content, 'utf8')
+  if (path.resolve(dst) !== path.resolve(filepath)) {
+    fs.unlinkSync(filepath)
+  }
+  appendREQTransitionLog(cfg, logBasename, fromState, status)
+  console.log(`✓ moved ${basename} → ${targetDir}`)
 }
 
 /**
@@ -328,4 +462,4 @@ function detectDomains(intention) {
   )
 }
 
-module.exports = { listREQs, parseREQStatus, rewriteREQStatus, moveREQ, newREQ, PROBES_CATALOG, detectDomains, localDateISO, toSlug }
+module.exports = { listREQs, listREQFiles, findREQ, parseREQStatus, rewriteREQStatus, moveREQ, newREQ, PROBES_CATALOG, detectDomains, localDateISO, toSlug }

package/src/validator/index.js

@@ -254,22 +254,97 @@ function contentHasMarker(content, markers) {
   return false
 }
 
-// adrIsDraft verifica se <adrBasename> contém "Status: Draft" buscando recursivamente nas adrDirs.
-function adrIsDraft(basename) {
-  return adrDraftStatusForRule(basename, null).draft
+// extractAdrHeaderStatus extrai o valor declarado na linha de cabeçalho
+// ("> Date: ... | Status: X") de um ADR. Ancorado à linha — não é substring livre sobre o
+// documento inteiro — para não confundir texto de prosa que mencione "Status: Draft"/"Proposed"
+// (ex: citações de código, exemplos) com o status real do artefato. Retorna '' se a linha não
+// existir.
+function extractAdrHeaderStatus(content) {
+  const marker = '| Status: '
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    const idx = trimmed.indexOf(marker)
+    if (idx >= 0) {
+      let rest = trimmed.slice(idx + marker.length)
+      const pipeIdx = rest.indexOf(' |')
+      if (pipeIdx >= 0) rest = rest.slice(0, pipeIdx)
+      return rest.trim()
+    }
+  }
+  return ''
 }
 
-function adrDraftStatusForRule(basename, messages) {
+// extractFrontmatterField extrai o valor de um campo do bloco frontmatter YAML
+// (delimitado por "---" ... "---" no início do arquivo). Retorna '' se o frontmatter
+// estiver ausente ou o campo não existir/estiver vazio.
+function extractFrontmatterField(content, field) {
+  if (!content.startsWith('---')) return ''
+  const rest = content.slice(3)
+  const end = rest.indexOf('\n---')
+  if (end < 0) return ''
+  const block = rest.slice(0, end)
+  for (const line of block.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed.startsWith(field + ':')) {
+      let val = trimmed.slice(field.length + 1).trim()
+      val = val.replace(/^["']|["']$/g, '')
+      return val
+    }
+  }
+  return ''
+}
+
+// resolveAdrStatus extrai o valor bruto do status de um ADR: frontmatter `status:`
+// primeiro — é o campo machine-readable canônico, o mesmo que os geradores (`adr new`,
+// NewADRDraft) escrevem e que a regra folder_status já usa como fonte de verdade — com
+// fallback para a linha de cabeçalho ("> Date: ... | Status: X") somente se o
+// frontmatter estiver ausente ou sem o campo (cobre ADRs legados sem frontmatter). Em um
+// ADR bem formado os dois concordam. ML-1D (2026-08-01): alinha o Node ao Go e ao
+// Python, que já liam frontmatter-first (ADR-2026-08-01-nocao-canonica-de-adr-nao-aceito).
+function resolveAdrStatus(content) {
+  const fm = extractFrontmatterField(content, 'status')
+  if (fm) return fm
+  return extractAdrHeaderStatus(content)
+}
+
+// adrNotAcceptedStatusForRule é o helper canônico de "ADR não aceito": único lugar que conhece o
+// vocabulário Draft/Proposed. Verdadeiro para ADR cujo status seja "Draft" ou "Proposed"; qualquer
+// outro status (Accepted, Superseded, Deprecated, Rejected, ...) conta como aceito por exclusão —
+// não há allowlist fechada de status aceitos.
+//
+// A fonte do status é resolveAdrStatus (frontmatter-first, fallback de cabeçalho — ver acima).
+// Crucial: o fallback de cabeçalho extrai o valor de UMA linha específica
+// (extractAdrHeaderStatus), não faz content.includes('Status: Draft') sobre o documento
+// inteiro — esse era o defeito do código herdado (adrDraftStatusForRule original): um ADR
+// com status real "Accepted" mas cuja prosa cita literalmente a string "Status: Draft"
+// (ex: este próprio ADR, que documenta o bug) seria classificado como não aceito. Ver
+// vault/notes para o caso concreto que expôs isso.
+function adrNotAcceptedStatusForRule(rule, basename, messages) {
   const p = findAdrFile(basename)
-  if (!p) return { draft: false, inspected: true }
+  if (!p) return { notAccepted: false, status: '', inspected: true }
   try {
-    return { draft: fs.readFileSync(p, 'utf8').includes('Status: Draft'), inspected: true }
+    const content = fs.readFileSync(p, 'utf8')
+    const status = resolveAdrStatus(content)
+    const notAccepted = status.toLowerCase() === 'draft' || status.toLowerCase() === 'proposed'
+    return { notAccepted, status, inspected: true }
   } catch (err) {
-    if (messages) messages.push(inspectionDiagnostic('blocked_by_draft_adr', p, err))
-    return { draft: false, inspected: false }
+    if (messages) messages.push(inspectionDiagnostic(rule, p, err))
+    return { notAccepted: false, status: '', inspected: false }
   }
 }
 
+// adrIsDraft verifica se <adrBasename> está em status não aceito (Draft ou Proposed) buscando
+// recursivamente nas adrDirs. Nome mantido por compatibilidade (chamadores existentes); delega no
+// helper canônico adrNotAcceptedStatusForRule.
+function adrIsDraft(basename) {
+  return adrDraftStatusForRule(basename, null).draft
+}
+
+function adrDraftStatusForRule(basename, messages) {
+  const result = adrNotAcceptedStatusForRule('blocked_by_draft_adr', basename, messages)
+  return { draft: result.notAccepted, inspected: result.inspected }
+}
+
 // validateWIPHasREQ — roadmaps em wip/ sem marker REQ no conteúdo → violation
 // Suporta modo by_agent via resolveWIPDirs.
 function validateWIPHasREQ() {
@@ -419,29 +494,10 @@ function validateWIPHasAcceptanceCriteria() {
   return violations
 }
 
-// readWIPConfig lê wip_limit e wip_by_squad do trackfw.yaml no CWD.
-// Retorna { limit: 1, bySquad: false } se o arquivo não existe ou campos ausentes.
-function readWIPConfig() {
-  const cfg = { limit: 1, bySquad: false }
-  let content
-  try {
-    content = fs.readFileSync('trackfw.yaml', 'utf8')
-  } catch (_) {
-    return cfg
-  }
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim()
-    if (trimmed.startsWith('wip_limit:')) {
-      const val = trimmed.slice('wip_limit:'.length).trim().split(/\s+/)[0]
-      const n = parseInt(val, 10)
-      if (!isNaN(n) && n > 0) cfg.limit = n
-    }
-    if (trimmed.startsWith('wip_by_squad:')) {
-      const val = trimmed.slice('wip_by_squad:'.length).trim().split(/\s+/)[0]
-      if (val === 'true') cfg.bySquad = true
-    }
-  }
-  return cfg
+// wipConfigFrom deriva { limit, bySquad } a partir do ProjectConfig já normalizado por
+// config.load() — nenhuma releitura de trackfw.yaml acontece aqui.
+function wipConfigFrom(cfg) {
+  return { limit: cfg.wipLimit > 0 ? cfg.wipLimit : 1, bySquad: !!cfg.wipBySquad }
 }
 
 // parseSquadFromFrontmatter extrai o valor do campo "squad:" de um arquivo markdown.
@@ -498,7 +554,7 @@ function validateWIPLimit() {
     return { violations, warnings }
   }
 
-  const wipCfg = readWIPConfig()
+  const wipCfg = wipConfigFrom(cfg)
 
   if (!wipCfg.bySquad) {
     if (files.length > wipCfg.limit) {
@@ -622,13 +678,63 @@ function validateREQsNotBlockedByDraftADRs() {
     const blockedADRs = parseBlockedADRs(filePath)
     for (const adrBasename of blockedADRs) {
       if (adrDraftStatusForRule(adrBasename, violations).draft) {
-        violations.push(`REQ ${path.basename(filePath)} is blocked by Draft ADR: ${adrBasename}`)
+        violations.push(`REQ ${path.basename(filePath)} is blocked by not-accepted ADR: ${adrBasename}`)
       }
     }
   }
   return violations
 }
 
+// reqStatusEquals compara o status de uma REQ (case-insensitive) contra o valor esperado.
+// Casa tanto o frontmatter ("status: X") quanto a linha de cabeçalho ("> Date: ... | Status: X"),
+// mesma lógica de detecção usada por reqStatusIsOpen — duplicada aqui (em vez de generalizar
+// reqStatusIsOpen) para não alterar o comportamento de req_roadmap_lifecycle, que já a consome.
+function reqStatusEquals(content, status) {
+  const target = String(status).toLowerCase()
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    const idx = trimmed.indexOf(':')
+    if (idx >= 0 && trimmed.slice(0, idx).trim().toLowerCase() === 'status') {
+      return trimmed.slice(idx + 1).trim().replace(/^["']|["']$/g, '').toLowerCase() === target
+    }
+    const marker = '| Status: '
+    const markerIdx = trimmed.indexOf(marker)
+    if (markerIdx >= 0) {
+      let rest = trimmed.slice(markerIdx + marker.length)
+      const pipeIdx = rest.indexOf(' |')
+      if (pipeIdx >= 0) rest = rest.slice(0, pipeIdx)
+      return rest.trim().toLowerCase() === target
+    }
+  }
+  return false
+}
+
+// validateADRAcceptedWhenREQDone — REQ Done cujo ADR vinculado (campo "ADR:") não está aceito
+// (Draft ou Proposed, via o helper canônico adrNotAcceptedStatusForRule) → violation. Fecha a
+// lacuna que deixou um ADR Proposed atravessar sete REQs Done sem nenhum gate detectar.
+function validateADRAcceptedWhenREQDone() {
+  const cfg = config.load()
+  const files = resolveReqFiles(cfg)
+  const violations = []
+  for (const filePath of files) {
+    const content = readFileForRule('adr_accepted_when_req_done', filePath, violations)
+    if (content === null) continue
+    if (!reqStatusEquals(content, 'done')) continue
+
+    const adrRef = extractRefPath(content, 'ADR')
+    if (!adrRef) continue
+    const adrBasename = path.basename(adrRef)
+    const status = adrNotAcceptedStatusForRule('adr_accepted_when_req_done', adrBasename, violations)
+    if (status.notAccepted) {
+      const reqBasename = path.basename(filePath)
+      violations.push(
+        `REQ "${reqBasename}" is Done but linked ADR "${adrBasename}" is not accepted (status: ${status.status})`
+      )
+    }
+  }
+  return violations
+}
+
 // blockedREQs retorna mapa de reqBasename → [adrBasenames Draft] para uso em getStatus()
 function blockedREQs() {
   const cfg = config.load()
@@ -652,37 +758,23 @@ function blockedREQs() {
   return result
 }
 
-// readGovernanceMode lê governance_mode e lenient_until do trackfw.yaml no CWD.
-// Retorna { mode: 'strict', lenientUntil: null } se o arquivo não existe ou campos ausentes.
-function readGovernanceMode() {
-  let content
-  try {
-    content = fs.readFileSync('trackfw.yaml', 'utf8')
-  } catch (_) {
-    return { mode: 'strict', lenientUntil: null }
-  }
-  let mode = 'strict'
+// governanceModeFrom deriva { mode, lenientUntil } a partir do ProjectConfig já normalizado por
+// config.load() — nenhuma releitura de trackfw.yaml acontece aqui. cfg.governanceMode chega como
+// o valor bruto do campo (string vazia se ausente); cfg.lenientUntil chega como a data literal
+// (ex.: "2026-08-02"), convertida aqui para Date.
+function governanceModeFrom(cfg) {
+  const mode = cfg.governanceMode ? cfg.governanceMode : 'strict'
   let lenientUntil = null
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim()
-    if (trimmed.startsWith('governance_mode:')) {
-      const val = trimmed.slice('governance_mode:'.length).trim().split(/\s+/)[0]
-      if (val) mode = val
-    }
-    if (trimmed.startsWith('lenient_until:')) {
-      const val = trimmed.slice('lenient_until:'.length).trim().split(/\s+/)[0]
-      if (val) {
-        const d = new Date(val)
-        if (!isNaN(d.getTime())) lenientUntil = d
-      }
-    }
+  if (cfg.lenientUntil) {
+    const d = new Date(cfg.lenientUntil)
+    if (!isNaN(d.getTime())) lenientUntil = d
   }
   return { mode, lenientUntil }
 }
 
 // isLenient retorna true se o projeto está em modo lenient e o prazo não expirou.
 function isLenient() {
-  const gm = readGovernanceMode()
+  const gm = governanceModeFrom(config.load())
   if (gm.mode !== 'lenient') return false
   if (!gm.lenientUntil) return true
   return new Date() < gm.lenientUntil
@@ -690,7 +782,7 @@ function isLenient() {
 
 // lenientUntilDate retorna a data de expiração formatada (YYYY-MM-DD) ou ''.
 function lenientUntilDate() {
-  const gm = readGovernanceMode()
+  const gm = governanceModeFrom(config.load())
   if (gm.mode !== 'lenient' || !gm.lenientUntil) return ''
   return gm.lenientUntil.toISOString().slice(0, 10)
 }
@@ -735,7 +827,7 @@ function extractRefPath(content, field) {
       let val = trimmed.slice(idx + 1).trim()
       if (!val || val === '—' || val === '-' || val === '–') return null
       val = val.split(/\s+/)[0]
-      val = val.replace(/^["']|["']$/g, '')
+      val = val.replace(/^["'`]|["'`]$/g, '')
       if (val.endsWith('.md')) return val
     }
   }
@@ -1131,6 +1223,7 @@ async function validateUnfiltered() {
   applyRule('filename_uniqueness',  validateFilenameUniqueness(),          violations, warnings)
   applyRule('branch_has_wip_roadmap', validateBranchHasWIPRoadmap(),      violations, warnings)
   applyRule('blocked_by_draft_adr', validateREQsNotBlockedByDraftADRs(),  violations, warnings)
+  applyRule('adr_accepted_when_req_done', validateADRAcceptedWhenREQDone(), violations, warnings)
   applyRule('note_orphan',           validateNoteOrphan(),                 violations, warnings)
 
   // Regras configuráveis via applyRule (popula _itemMeta automaticamente)
@@ -1187,10 +1280,60 @@ async function validate() {
   return { violations, warnings }
 }
 
+// ROADMAP_STATES enumera os 6 estados de roadmap na ordem exibida pelo bloco Inventory.
+const ROADMAP_STATES = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']
+
+// buildInventorySection monta o bloco "📊 Inventory" — contagem agregada de ADRs, REQs
+// (discriminadas por status real via reqStatusEquals) e roadmaps (pelos 6 estados, incluindo
+// "analyzing", historicamente omitido). Namespacing-agnóstico: agrega através de
+// resolveStateDirs()/resolveReqFiles(), que já resolvem flat vs by_agent.
+function buildInventorySection(cfg) {
+  let adrCount = 0
+  for (const adrDir of cfg.adrDirs || []) {
+    adrCount += walkDirMdWithPathsForRule('status_inventory', adrDir, []).length
+  }
+
+  const reqFiles = resolveReqFiles(cfg)
+  let reqOpen = 0
+  let reqDone = 0
+  let reqClosed = 0
+  for (const filePath of reqFiles) {
+    let content
+    try {
+      content = fs.readFileSync(filePath, 'utf8')
+    } catch (_) {
+      continue
+    }
+    if (reqStatusEquals(content, 'open')) reqOpen++
+    else if (reqStatusEquals(content, 'done')) reqDone++
+    else if (reqStatusEquals(content, 'closed')) reqClosed++
+  }
+
+  const roadmapCounts = {}
+  let roadmapTotal = 0
+  for (const state of ROADMAP_STATES) {
+    let count = 0
+    for (const dir of resolveStateDirs(cfg, state)) {
+      count += listDir(dir).length
+    }
+    roadmapCounts[state] = count
+    roadmapTotal += count
+  }
+
+  let section = '\n📊 Inventory\n'
+  section += `   ${'ADRs'.padEnd(12)}${adrCount}\n`
+  section += `   ${'REQs'.padEnd(12)}${reqFiles.length}  (${reqOpen} Open · ${reqDone} Done · ${reqClosed} Closed)\n`
+  section += `   ${'Roadmaps'.padEnd(12)}${roadmapTotal}\n`
+  section += `     backlog ${roadmapCounts.backlog} · analyzing ${roadmapCounts.analyzing} · wip ${roadmapCounts.wip}\n`
+  section += `     blocked ${roadmapCounts.blocked} · done ${roadmapCounts.done} · abandoned ${roadmapCounts.abandoned}\n`
+  return section
+}
+
 // getStatus retorna string formatada com o status de governança do projeto
 async function getStatus() {
   const cfg = config.load()
   let out = '── trackfw status ──────────────────────\n'
+  out += buildInventorySection(cfg)
 
   if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
     let agents = cfg.agents || []
@@ -1217,7 +1360,7 @@ async function getStatus() {
     out += `\n🔄 WIP (${wip.length})\n`
     for (const f of wip) out += `   ${f}\n`
 
-    const wipCfg = readWIPConfig()
+    const wipCfg = wipConfigFrom(cfg)
     if (wipCfg.bySquad && wip.length > 0) {
       const bySquad = {}
       for (const f of wip) {
@@ -1242,14 +1385,19 @@ async function getStatus() {
       for (const w of staleWIPs) out += `   ${w}\n`
     }
 
+    // Seção: REQs bloqueadas por ADRs não aceitos (Draft ou Proposed). O status exibido por
+    // ADR é resolvido via adrNotAcceptedStatusForRule (helper canônico) em vez de hardcodar
+    // "Draft" — blockedREQs() cobre ambos os status desde que delega em adrIsDraft/
+    // adrDraftStatusForRule, e um rótulo fixo "(Draft)" mentiria para um ADR Proposed.
     const blockedByDraft = blockedREQs()
     const blockedKeys = Object.keys(blockedByDraft)
     if (blockedKeys.length > 0) {
-      out += `\n⏳ REQs blocked by Draft ADRs (${blockedKeys.length})\n`
+      out += `\n⏳ REQs blocked by not-accepted ADRs (${blockedKeys.length})\n`
       for (const reqFile of blockedKeys) {
         out += `   ${reqFile}\n`
         for (const adr of blockedByDraft[reqFile]) {
-          out += `     → ${adr} (Draft)\n`
+          const { status } = adrNotAcceptedStatusForRule('blocked_by_draft_adr', adr, null)
+          out += `     → ${adr} (${status})\n`
         }
       }
     }
@@ -1291,8 +1439,6 @@ module.exports = {
   resolveStateDirs,
   resolveWIPDirs,
   resolveDoneDirs,
-  readGovernanceMode,
-  readWIPConfig,
   parseSquadFromFrontmatter,
   validateFrontmatterPresence,
   // novas funções ML-1B
@@ -1316,4 +1462,12 @@ module.exports = {
   isInsideDir,
   walkDirMdWithPaths,
   validateADRDirsExist,
+  // novas funções ML-1B (2026-08-01 — adr_accepted_when_req_done)
+  extractAdrHeaderStatus,
+  adrNotAcceptedStatusForRule,
+  reqStatusEquals,
+  validateADRAcceptedWhenREQDone,
+  // ML-1D (2026-08-01 — reconciliação de paridade: frontmatter-first)
+  extractFrontmatterField,
+  resolveAdrStatus,
 }