@ingeniomaps/cauce 0.43.0 → 0.46.0

package/engine/planning/contracts.js

@@ -2,9 +2,12 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
+const P = require('./parser')
+const { PLACEHOLDERS } = require('../core/onboarding')
 
 const TEST_TRACE = /^(?:n\/a\s*[—-]\s*.+|(?:A|C\d+)\s*(?:→|->)\s*\S.+)$/i
 const DECISION_TRACE = /\[(?:fuente|supuesto):\s*[^\]]+\]/i
+const COMMIT_TRACE = /^(?:n\/a\s*[—-]\s*.+|[0-9a-f]{7,40}\s+\S.*)$/i
 const EPIC_AUXILIARY_FILES = new Set(['notes.md', 'plan.md', 'research.md', 'spec.md'])
 
 function validTestTrace(value) {
@@ -17,13 +20,44 @@ function validDecisionTrace(value) {
   return !text || DECISION_TRACE.test(text)
 }
 
-function validateDoneEntry(entry) {
+// El campo apunta al artefacto entregado, y el único puntero que no se puede escribir de memoria es el
+// sha. La salida explícita existe porque hay tareas que no producen commit —abrir una fila en
+// HUMAN_ACTIONS, registrar un informe—, y forzarlas a llenar el campo produce un sha inventado, que es
+// peor que la ausencia: parece evidencia.
+function validCommitTrace(value) {
+  // Se corta en cada `|`, y en un `;` sólo cuando detrás viene un sha: el `;` aparece también dentro del
+  // paréntesis final —`(api@main; sin footer Task:)`— y cortar ahí convertiría una nota en un commit que
+  // falta. Cada tramo responde por sí mismo; validar sólo el primero dejaba pasar la mitad sin artefacto.
+  return String(value || '').trim().split(/\s*(?:\||;(?=\s*[0-9a-f]{7,40}\s))\s*/)
+    .every((part) => COMMIT_TRACE.test(part.trim()))
+}
+
+// Los criterios que la evidencia realmente rastrea. `n/a — razón` no rastrea ninguno a propósito: es
+// la salida explícita, y como lleva su razón escrita se lee en el propio DONE sin que nadie la cruce.
+function testedCriteria(value) {
+  return String(value || '').split(/\s*;\s*/).filter(Boolean)
+    .map((item) => ((item.match(/^(C\d+)\s*(?:→|->)/i) || [])[1] || '').toUpperCase())
+    .filter(Boolean)
+}
+
+// `cited` son los criterios que la historia declaró cubrir. Rastrear de más es legítimo —una prueba
+// puede cerrar dos criterios—; lo que no puede es que el criterio citado se quede sin ninguna
+// aserción, porque la épica cierra igual y nadie vuelve a mirarlo.
+function validateDoneEntry(entry, cited = []) {
   const at = `${entry.source} ${entry.slug}`
   const errors = []
   if (!entry.tests) errors.push(`${at}: falta tests:`)
   else if (!validTestTrace(entry.tests)) {
     errors.push(`${at}: tests debe rastrear A/CN → prueba o justificar n/a — razón`)
   }
+  const traced = testedCriteria(entry.tests)
+  if (traced.length) {
+    const missing = cited.filter((id) => !traced.includes(id))
+    if (missing.length) errors.push(`${at}: la historia cita ${missing.join(', ')} y tests: no lo rastrea`)
+  }
+  if (entry.commit && !validCommitTrace(entry.commit)) {
+    errors.push(`${at}: commit debe apuntar a <sha> <asunto> o justificar n/a — razón`)
+  }
   if (!validDecisionTrace(entry.decisions)) {
     errors.push(`${at}: decisions debe citar [fuente: ...] o [supuesto: ...]`)
   }
@@ -51,6 +85,12 @@ function validateEpic(epic, done = new Set()) {
   for (const criterion of epic.criteria) {
     if (!covered.has(criterion.id)) errors.push(`${at}: ${criterion.id} no está cubierto por ninguna historia`)
   }
+  // Un borrador se escribe con los bordes marcados; activarla es decir que ya no quedan. Cerrarla con uno
+  // adentro es peor: la evidencia queda apoyada sobre algo que nadie decidió.
+  if (epic.status !== 'open' && epic.placeholders && epic.placeholders.length) {
+    errors.push(`${at}: ${epic.status} con ${epic.placeholders.length} marcador(es) sin resolver `
+      + `— "${epic.placeholders[0]}"`)
+  }
   if (epic.status === 'closed') {
     const missing = epic.stories.filter((story) => !done.has(story.slug))
     if (missing.length) errors.push(`${at}: closed sin evidencia para ${missing.map((story) => story.slug).join(', ')}`)
@@ -88,7 +128,289 @@ function validateRoadmapStructure(dir) {
   return errors
 }
 
+// El BACKLOG es la única cola, y su lector descarta en silencio lo que no cumple el contrato: una
+// viñeta mal escrita no está en cola, no aparece en `tree` y no la toma nadie, sin que nada falle.
+// Se juzga sólo lo que vive bajo un hito —el encabezado del archivo es prosa— y sólo las viñetas,
+// para no confundir con un error el texto que acompaña a una tarea.
+function validateBacklogStructure(dir) {
+  const text = P.withoutComments(P.read(path.join(dir, 'BACKLOG.md')))
+  const errors = []
+  let milestone = ''
+  for (const line of text.split('\n')) {
+    const heading = line.match(P.MILESTONE_HEADING)
+    if (heading) { milestone = heading[1]; continue }
+    if (/^##\s+Hito\b/.test(line)) {
+      errors.push(`BACKLOG "${line.trim()}": encabezado inválido; se escribe ## Hito <slug> — <Título>, `
+        + 'y sin él las tareas que vienen abajo quedan huérfanas')
+      milestone = ''
+      continue
+    }
+    if (/^##\s+/.test(line)) { milestone = ''; continue }
+    if (!milestone || !/^\s*[-*]\s+\S/.test(line) || P.TASK_LINE.test(line)) continue
+    const lane = line.match(P.TASK_LINE_ANY_LANE)
+    if (lane) {
+      errors.push(`BACKLOG ${lane[1].trim()}: lane "${lane[2]}" no existe; usá ${P.LANES.join(' | ')}, `
+        + 'o dejá la tarea sin clasificar')
+      continue
+    }
+    const at = `BACKLOG hito ${milestone}: no la lee nadie`
+    if (/^-\s+\[[xX]\]/.test(line)) {
+      errors.push(`${at} — ${line.trim().slice(0, 60)}. Una tarea terminada se mueve a DONE.md, no se tilda acá.`)
+      continue
+    }
+    errors.push(`${at} — ${line.trim().slice(0, 60)}. Una tarea se escribe `
+      + '`- [ ] **slug** [lane] — descripción`, con `(→ CN) (epic: NNN)` o `_Aceptación:_` después del guión.')
+  }
+  return errors
+}
+
+// El número de una regla es su identificador, y lo cita todo el sistema: cargos, workflows, plantillas
+// y entradas de DONE. El override se declara escribiendo un archivo con el mismo nombre que el del
+// sistema —ahí redefinir sus números es el punto—; en cualquier otro archivo, reusar un `R` crea una
+// segunda definición que nadie declaró y que ninguna herramienta veía. Las propias se numeran `P`.
+function ruleIds(file) {
+  return [...P.read(file).matchAll(/^##\s+([A-Z]\d+)\s+[—-]/gm)].map((match) => match[1])
+}
+
+function validateRules(dir) {
+  const rules = path.join(dir, 'rules')
+  const owner = new Map()
+  const errors = []
+  const files = (sub) => {
+    try {
+      return fs.readdirSync(path.join(rules, sub), { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'README.md')
+        .map((entry) => entry.name).sort()
+    } catch { return [] }
+  }
+  const system = new Set(files('system'))
+  for (const name of system) {
+    for (const id of ruleIds(path.join(rules, 'system', name))) {
+      if (owner.has(id)) errors.push(`rules/system/${name}: ${id} ya lo define ${owner.get(id)}`)
+      else owner.set(id, `rules/system/${name}`)
+    }
+  }
+  for (const name of files('')) {
+    // El override se declara por nombre: redefinir los números del archivo que reemplaza es su función.
+    if (system.has(name)) continue
+    for (const id of ruleIds(path.join(rules, name))) {
+      const definedBy = owner.get(id)
+      if (!definedBy) { owner.set(id, `rules/${name}`); continue }
+      errors.push(definedBy.startsWith('rules/system/')
+        ? `rules/${name}: ${id} ya lo define ${definedBy}; una regla propia se numera P1..Pn, `
+          + 'o vive en un archivo con el mismo nombre para declarar el override'
+        : `rules/${name}: ${id} ya lo define ${definedBy}`)
+    }
+  }
+  return errors
+}
+
+// Una decisión que no dice si rige no decide nada, y el molde traía el menú entero en la línea de estado:
+// tres de las dieciséis decisiones escritas con este modelo se publicaron con el menú intacto. Presentar
+// las opciones no obliga a elegir; esto sí. Las secciones son las cuatro que se escriben siempre —las
+// alternativas quedan en el molde sin exigirse, porque pedirlas rechazaría quince decisiones que existen—.
+const ADR_STATES = ['Propuesto', 'Aceptado', 'Obsoleto']
+const ADR_SUPERSEDED = /^Reemplazada por \[[^\]]+\]\([^)]+\)(?: \(\d{4}-\d{2}-\d{2}\))?$/
+const ADR_SECTIONS = ['Contexto', 'Decisión', 'Consecuencias', 'Estado de implementación']
+
+function validateAdrFile(at, text) {
+  const errors = []
+  const declared = ((text.match(/^\*\*Estado:\*\*\s*(.+?)\s*$/m) || [])[1] || '').trim()
+  if (!declared) errors.push(`${at}: falta **Estado:**`)
+  else if (declared.includes('|')) errors.push(`${at}: el estado sigue siendo el menú de la plantilla; elegí uno`)
+  else if (!ADR_STATES.includes(declared) && !ADR_SUPERSEDED.test(declared)) {
+    errors.push(`${at}: estado "${declared}" fuera de ${ADR_STATES.join(' | ')} `
+      + '| Reemplazada por [NNN](NNN-slug.md)')
+  }
+  for (const section of ADR_SECTIONS) {
+    if (!new RegExp(`^##\\s+${section}\\s*$`, 'm').test(text)) errors.push(`${at}: falta ## ${section}`)
+  }
+  return errors
+}
+
+// El nombre lleva el id porque de ahí sale la identidad con que se detecta un override, y porque una
+// decisión se cita por número. Sin él, el archivo existe y no lo alcanza ninguna referencia.
+function validateAdr(dir) {
+  const adr = path.join(dir, 'adr')
+  const errors = []
+  const numbers = new Map()
+  const scan = (sub, pattern) => {
+    let entries = []
+    try { entries = fs.readdirSync(path.join(adr, sub), { withFileTypes: true }) } catch { return }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+      if (entry.name === 'README.md' || entry.name === '000-template.md') continue
+      const at = `adr/${sub ? `${sub}/` : ''}${entry.name}`
+      const id = entry.name.match(pattern)
+      if (!id) {
+        errors.push(`${at}: nadie lo lee como decisión. Una ADR se nombra NNN-<slug>.md, `
+          + 'y la del sistema <ID>-NNN-<slug>.md en system/.')
+        continue
+      }
+      if (numbers.has(id[1])) errors.push(`${at}: ${id[1]} ya lo usa ${numbers.get(id[1])}`)
+      else numbers.set(id[1], at)
+      errors.push(...validateAdrFile(at, P.read(path.join(adr, sub, entry.name))))
+    }
+  }
+  scan('', /^(\d{3})-[a-z0-9-]+\.md$/)
+  scan('system', /^([A-Z][A-Z0-9]*-\d{3})-[a-z0-9-]+\.md$/)
+  return errors
+}
+
+// Todo lo que se juzga sobre el estado ya leído: épicas, hitos, tareas, WIP, evidencia y acciones
+// humanas. Vive acá y no en el CLI porque es de la misma clase que sus vecinas —`validateEpic`,
+// `validateDoneEntry`, `validateRules`— y estaba creciendo del otro lado sólo porque ahí era más
+// rápido escribirla. No lee nada: recibe el estado, así que se prueba sin tocar disco.
+function validateState({ epics, milestones, done, wip, roles = new Set(), humanActions = [] }) {
+  const errors = []
+  const epicNums = new Set()
+  const storySlugs = new Set()
+  const backlogSlugs = new Set(milestones.flatMap((milestone) => milestone.tasks).map((task) => task.slug))
+  for (const duplicate of done.duplicates) errors.push(`DONE duplicado: ${duplicate}`)
+  for (const epic of epics) {
+    const at = `roadmap/${epic.file}`
+    errors.push(...validateEpic(epic, done.set))
+    if (!/^\d{3}$/.test(epic.num)) errors.push(`${at}: epic debe ser NNN`)
+    if (epicNums.has(epic.num)) errors.push(`${at}: número de épica duplicado ${epic.num}`)
+    epicNums.add(epic.num)
+    if (!epic.title) errors.push(`${at}: falta title`)
+    if (!P.EPIC_STATES.includes(epic.status)) errors.push(`${at}: status inválido "${epic.status}"`)
+    if (!epic.criteria.length) errors.push(`${at}: falta al menos un criterio observable`)
+    if (!epic.stories.length) errors.push(`${at}: falta al menos una historia`)
+    if (!epic.hasContext) errors.push(`${at}: falta "## Contexto relevante"`)
+    const criteria = new Set(epic.criteria.map((criterion) => criterion.id))
+    for (const story of epic.stories) {
+      if (storySlugs.has(story.slug)) errors.push(`${at}: slug de historia duplicado ${story.slug}`)
+      storySlugs.add(story.slug)
+      if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(story.slug)) errors.push(`${at}: slug inválido ${story.slug}`)
+      if (!story.criteria.length) errors.push(`${at}: ${story.slug} no rastrea a un criterio`)
+      for (const criterion of story.criteria) {
+        if (!criteria.has(criterion)) errors.push(`${at}: ${story.slug} cita ${criterion}, que no existe`)
+      }
+      if (!story.service) errors.push(`${at}: ${story.slug} no declara (service: <ruta>)`)
+    }
+    const missing = epic.stories.filter((story) => !done.set.has(story.slug))
+    if (epic.status === 'active' && !missing.length) errors.push(`${at}: active sin historias pendientes; debe cerrar`)
+  }
+
+  const milestoneSlugs = new Set()
+  for (const milestone of milestones) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(milestone.slug)) errors.push(`hito con slug inválido: ${milestone.slug}`)
+    if (milestoneSlugs.has(milestone.slug)) errors.push(`hito duplicado: ${milestone.slug}`)
+    milestoneSlugs.add(milestone.slug)
+    for (const task of milestone.tasks) {
+      if (!task.service) errors.push(`BACKLOG ${task.slug}: falta (service: <ruta>)`)
+      // Un cargo mal escrito se queda sin resolver en la fase que lo invoca, y ahí ya se gastó todo
+      // lo anterior: la revisión desaparece sin que nada falle. Se contrasta acá, antes de ejecutar.
+      // Con el catálogo vacío no hay nada contra qué contrastar —una instancia sin la dependencia
+      // instalada—, y exigirlo igual convertiría cada cast en un error.
+      for (const slug of [task.cast.build, ...task.cast.review].filter(Boolean)) {
+        if (roles.size && !roles.has(slug)) {
+          errors.push(`BACKLOG ${task.slug}: el cast nombra ${slug}, que no está en el catálogo`)
+        }
+      }
+      if (!task.acceptance && !(task.epic && task.criteria.length)) {
+        errors.push(`BACKLOG ${task.slug}: falta aceptación explícita o criterio heredado`)
+      }
+      // La misma puerta que la épica, un piso abajo: la épica rechaza el marcador al activarse, pero la
+      // tarea es lo que un runner recibe. Se juzga la frase que `context` le va a entregar —propia o
+      // heredada del criterio—, porque en las dos formas llega igual y se decide sola.
+      const inherited = epics.find((epic) => epic.num === task.epic)?.criteria
+        .filter((criterion) => task.criteria.includes(criterion.id))
+        .map((criterion) => criterion.text).join(' ') || ''
+      const acceptance = (task.acceptance || inherited).trim()
+      if (acceptance && PLACEHOLDERS.test(acceptance)) {
+        errors.push(`BACKLOG ${task.slug}: la aceptación no está decidida — "${acceptance.slice(0, 80)}"`)
+      }
+      const storyExists = epics.some((epic) => {
+        return epic.num === task.epic && epic.stories.some((story) => story.slug === task.slug)
+      })
+      if (task.epic && !storyExists) {
+        errors.push(`BACKLOG ${task.slug}: no existe en epic-${task.epic}`)
+      }
+      if (done.set.has(task.slug)) errors.push(`${task.slug}: está en BACKLOG y DONE`)
+    }
+  }
+
+  if (wip && !backlogSlugs.has(wip.task) && !done.set.has(wip.task)) {
+    errors.push(`WIP ${wip.task}: no existe en BACKLOG ni DONE`)
+  }
+  // El WIP es el punto de retorno tras una interrupción, y el protocolo manda seguir desde el primer
+  // paso sin tildar. Un plan que el motor no puede contar se lee como un plan terminado, así que la
+  // recuperación se queda sin de dónde retomar justo cuando es lo único que quedó del trabajo.
+  if (wip && !wip.complete && !wip.pending) {
+    errors.push(`WIP ${wip.task}: el plan no tiene pasos que el motor pueda contar; `
+      + 'se escriben `1. [ ] paso`')
+  }
+  for (const row of humanActions) {
+    if (!row.valid) {
+      errors.push(`HUMAN_ACTIONS ${row.task}: estado "${row.state}" fuera de `
+        + `${P.HUMAN_ACTION_STATES.join(' | ')}; mientras no se entienda, la tarea queda bloqueada`)
+    }
+  }
+
+  for (const entry of done.entries) {
+    if (!entry.acceptance) errors.push(`${entry.source} ${entry.slug}: falta acept:`)
+    if (!entry.done) errors.push(`${entry.source} ${entry.slug}: falta done:`)
+    if (!entry.qa) errors.push(`${entry.source} ${entry.slug}: falta qa:`)
+    if (!entry.commit) errors.push(`${entry.source} ${entry.slug}: falta commit:`)
+    // Los criterios que la historia declaró cubrir: los cita el roadmap, no la entrada de DONE, así que
+    // el cruce sólo existe si la entrada dice de qué épica viene.
+    const story = epics.find((epic) => epic.num === entry.epic)?.stories
+      .find((candidate) => candidate.slug === entry.slug)
+    errors.push(...validateDoneEntry(entry, story ? story.criteria : []))
+  }
+  return errors
+}
+
+// Los umbrales de R17, contados. La regla existía desde antes y nada la medía: una épica de veinte
+// criterios pasaba `check` sin una queja, siempre que cada uno tuviera su historia. Es la enumeración
+// que nadie contrasta de la que habla R15, y acá el que no contrastaba era el motor.
+//
+// Cruzar el umbral no es el error: R17 dispara la división, no la decide, y dejar la unidad entera es
+// una salida legítima. El error es cruzarlo **sin decidir**. Por eso lo que se exige es la razón —
+// `(sin partir: …)`, la misma forma parentética que `(service: …)`—, y con ella puesta la unidad pasa
+// en silencio. Avisar igual entrenaría a ignorar el aviso; no exigir nada dejaba la escapatoria sin
+// rastro, que era prosa sin mecanismo: exactamente lo que R17 fue hasta que esto existió.
+//
+// Fijos, sin configurar. La salida ya está adentro de la regla y deja rastro en el artefacto; un umbral
+// configurable agrega una segunda salida que no lo deja, porque se sube el día que molesta —o sea
+// cuando está funcionando— y queda silenciado para todos sin que nadie lo decida caso por caso. R7 sí
+// deja los suyos al proyecto, pero con su razón: dependen del lenguaje y de la superficie. Cinco
+// condiciones que un plan tiene que satisfacer a la vez no dependen de ninguna de las dos.
+const R17 = { taskCriteria: 5, epicCriteria: 7, milestoneTasks: 9 }
+
+// Se cuenta lo que está estructurado: criterios de la épica, criterios que hereda una tarea, tareas del
+// hito. La aceptación escrita en prosa no se cuenta —cuántas condiciones tiene una frase es una lectura,
+// y un número inventado ahí sería peor que ninguno—; ésa la mira el review, que para eso está R3.
+function oversizedUnits({ epics = [], milestones = [] }) {
+  const errors = []
+  const decidir = (what, count, limit) =>
+    `${what}: ${count} (umbral ${limit} de R17). Revisá si son dos resultados con vidas distintas y `
+    + 'partilo; si es uno solo, partirlo lo empeora — dejalo entero agregando "(sin partir: <razón>)"'
+  const juzgar = (unit, what, count, limit) => {
+    if (count > limit && !unit.noSplit) errors.push(decidir(what, count, limit))
+  }
+  for (const epic of epics) {
+    juzgar(epic, `roadmap/${epic.file}: criterios`, epic.criteria.length, R17.epicCriteria)
+  }
+  for (const milestone of milestones) {
+    juzgar(milestone, `hito ${milestone.slug}: tareas`, milestone.tasks.length, R17.milestoneTasks)
+    for (const task of milestone.tasks) {
+      juzgar(task, `BACKLOG ${task.slug}: criterios`, task.criteria.length, R17.taskCriteria)
+    }
+  }
+  return errors
+}
+
 module.exports = {
+  testedCriteria,
+  validateState,
+  oversizedUnits,
+  validateAdr,
+  validateRules,
+  validateBacklogStructure,
+  validCommitTrace,
   validDecisionTrace,
   validTestTrace,
   validateDoneEntry,

package/engine/planning/parser.js

@@ -4,21 +4,45 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
+const { frontmatter: fields } = require('../core/frontmatter')
+const { PLACEHOLDERS } = require('../core/onboarding')
 
 const EPIC_STATES = ['open', 'active', 'closed']
 
+// Vocabulario común de paradas. Una parada sin nombre obliga a quien la recibe —persona, supervisor o
+// workflow— a reconstruir del estado entero qué pasó, y es lo primero que se pierde cuando cada runner
+// inventa su propia frase. `context` emite las dos que puede determinar solo; el resto las nombra la
+// fase que para.
+const STOP_REASONS = [
+  'awaiting-review', 'blocked-on-human', 'not-ready', 'plan-rejected', 'review-unresolved',
+  'verify-regression', 'verify-inconsistent', 'qa-failed', 'commit-failed', 'budget-low',
+]
+
+// El contrato de una línea de BACKLOG, en un solo lugar: lo usa el lector para armar la cola y el
+// validador para rechazar lo que el lector va a descartar. Separados, el validador aprobaba la forma
+// que el lector no leía, que es la manera más cara de tener las dos cosas.
+const MILESTONE_HEADING = /^##\s+Hito\s+([^\s]+)\s+[—-]\s+(.+)$/
+
+// Los carriles, en orden de ceremonia creciente. El orden es parte del vocabulario: la prosa que los
+// describe va de menos a más y `check` lo contrasta, porque un carril leído fuera de orden se elige por
+// su nombre y no por su criterio.
+const LANES = ['express', 'directo', 'lite', 'full']
+const TASK_LINE = new RegExp(
+  String.raw`^-\s+\[\s\]\s+\*\*([^*]+)\*\*\s*(?:\[(${LANES.join('|')})\])?\s+[—-]\s+(.+)$`,
+)
+// Lo mismo con cualquier tag: distingue el lane inexistente de la línea sin lane, que es un estado
+// legítimo. Sin esa diferencia las dos caían en «no la lee nadie» y la corrección no era la misma.
+const TASK_LINE_ANY_LANE = /^-\s+\[\s\]\s+\*\*([^*]+)\*\*\s*\[([^\]]+)\]\s+[—-]\s+/
+
 function read(file) {
   try { return fs.readFileSync(file, 'utf8') } catch { return '' }
 }
 
+// Los contratos de planning leen un campo por nombre y no el objeto entero: devolver una función evita
+// que cada llamador tenga que preguntar si la clave existe antes de usarla.
 function frontmatter(text) {
-  const block = (text.match(/^---\s*\n([\s\S]*?)\n---/m) || [])[1] || ''
-  const values = new Map()
-  for (const line of block.split('\n')) {
-    const match = line.match(/^([\w-]+):\s*(.*)$/)
-    if (match) values.set(match[1], match[2].trim().replace(/^['"]|['"]$/g, ''))
-  }
-  return (key) => values.get(key) || ''
+  const values = fields(text)
+  return (key) => values[key] || ''
 }
 
 function section(text, heading) {
@@ -46,6 +70,12 @@ function epicFiles(dir) {
   return files
 }
 
+// La razón por la que una unidad cruza el umbral de R17 y sigue entera. Se escribe con la misma forma
+// parentética que el resto del contrato —`(service: …)`, `(epic: 001)`—, y se busca en el texto que es
+// de esa unidad y de ninguna otra: el archivo entero para la épica, la línea del encabezado para el
+// hito, la línea de la tarea para la tarea.
+const noSplitReason = (text) => ((text.match(/\(sin partir:\s*([^)]+)\)/i) || [])[1] || '').trim()
+
 function criteriaRefs(text) {
   const refs = []
   const groups = [
@@ -65,8 +95,16 @@ function readEpics(dir) {
   return epicFiles(dir).map(({ name, file }) => {
     const text = read(file)
     const field = frontmatter(text)
-    const criteria = [...section(text, /Criterios/i).matchAll(/^-\s+\*\*(C\d+)(?:[^*]*)\*\*\s+[—-]\s+(.+)$/gm)]
-      .map((match) => ({ id: match[1], text: match[2].trim() }))
+    // Mismo corte que ya se arregló para las historias: con la bandera `m`, `$` casa fin de línea, así
+    // que un criterio envuelto perdía todo lo que venía detrás del salto —normalmente cómo se verifica
+    // y qué debe seguir funcionando—. Se lee hasta el próximo criterio o el fin de la sección, y se
+    // devuelve en una sola línea porque quien lo recibe lo lee como aceptación, no como markdown.
+    const criterionPattern = new RegExp(
+      String.raw`^-\s+\*\*(C\d+)(?:[^*]*)\*\*\s+[—-]\s+([\s\S]*?)(?=\n-\s+\*\*C\d+|(?![\s\S]))`,
+      'gm',
+    )
+    const criteria = [...section(text, /Criterios/i).matchAll(criterionPattern)]
+      .map((match) => ({ id: match[1], text: match[2].trim().replace(/\s*\n\s*/g, ' ') }))
     // `(?![\s\S])` y no `$`: con la bandera `m` el `$` casa fin de **línea**, así que el cuerpo no ávido
     // cortaba en el primer salto y una historia envuelta perdía su `(service: …)` y sus `(→ CN)`. El
     // error que salía era «no declara (service: <ruta>)» — culpaba al autor de algo que sí había escrito.
@@ -91,31 +129,54 @@ function readEpics(dir) {
       criteria,
       stories,
       hasContext: /^##\s+Contexto relevante/im.test(text),
+      noSplit: noSplitReason(text),
+      // Las líneas que todavía no decidieron nada. Se guardan enteras y no como un booleano porque el
+      // error tiene que decir cuál es: «tiene un marcador» manda a releer la épica entera.
+      placeholders: text.split('\n').map((line) => line.trim())
+        .filter((line) => line && PLACEHOLDERS.test(line)),
     }
   }).filter((epic) => epic.status !== 'template' && epic.num !== '000')
 }
 
+// El reparto viaja en la línea de la tarea —`(cast: quien-entrega → quien-revisa, otro)`—, y la
+// flecha es lo que los separa. Los revisores son opcionales porque el lane más barato no tiene
+// ninguno, y el reparto entero también: una tarea sin clasificar es el estado que dispara al
+// clasificador, no un error. Devuelve siempre la forma completa para que nadie tenga que preguntar
+// si el campo existe antes de leerlo.
+function readCast(rest) {
+  const raw = ((rest.match(/\(cast:\s*([^)]+)\)/i) || [])[1] || '').trim()
+  const [build, reviewers] = raw.split(/\s*(?:→|->)\s*/)
+  return {
+    build: (build || '').trim(),
+    review: (reviewers || '').split(',').map((slug) => slug.trim()).filter(Boolean),
+  }
+}
+
 function readBacklog(dir) {
   const text = withoutComments(read(path.join(dir, 'BACKLOG.md')))
   const milestones = []
   let current = null
   for (const line of text.split('\n')) {
-    const heading = line.match(/^##\s+Hito\s+([^\s]+)\s+[—-]\s+(.+)$/)
+    const heading = line.match(MILESTONE_HEADING)
     if (heading) {
-      current = { slug: heading[1], title: heading[2].trim(), heading: line.slice(3), tasks: [] }
+      current = {
+        slug: heading[1], title: heading[2].trim(), heading: line.slice(3),
+        noSplit: noSplitReason(line), tasks: [],
+      }
       milestones.push(current)
       continue
     }
     if (/^##\s+/.test(line)) current = null
-    const task = line.match(/^-\s+\[\s\]\s+\*\*([^*]+)\*\*\s*(?:\[(directo|lite|full)\])?\s+[—-]\s+(.+)$/)
+    const task = line.match(TASK_LINE)
     if (!task || !current) continue
     const rest = task[3]
     current.tasks.push({
-      slug: task[1].trim(), tier: task[2] || '',
+      slug: task[1].trim(), tier: task[2] || '', cast: readCast(rest),
       epic: ((rest.match(/\(epic:\s*(\d{3})\)/) || [])[1] || ''),
       service: ((rest.match(/\(service:\s*([^)]+)\)/) || [])[1] || '').trim(),
       acceptance: ((rest.match(/_Aceptaci[oó]n:\s*([^_]+)_/i) || [])[1] || '').trim(),
       criteria: criteriaRefs(rest),
+      noSplit: noSplitReason(rest),
     })
   }
   return milestones
@@ -154,6 +215,29 @@ function readDone(dir) {
   return { entries, set: new Set(entries.map((entry) => entry.slug)), duplicates: [...new Set(duplicates)] }
 }
 
+// Vocabulario cerrado del Estado de `HUMAN_ACTIONS.md`. Es cerrado porque de este campo depende que una
+// tarea se pueda tomar, y quien lo escribe no recibe ninguna señal de haberlo escrito mal: cualquier
+// palabra de fuera del vocabulario deja la fila abierta y su tarea bloqueada sin que nada lo diga.
+const HUMAN_ACTION_STATES = ['pendiente', 'resuelta']
+
+// Se lee por el principio de la celda —no por `includes`— para que el detalle que acompaña al estado
+// («resuelta 2026-08-17») siga valiendo sin que una palabra suelta dentro de un texto largo resuelva
+// una fila que sigue abierta. `valid` distingue la fila mal escrita de la fila pendiente: las dos
+// bloquean, pero sólo una es un error que hay que reportar.
+function readHumanActions(dir) {
+  const rows = withoutComments(read(path.join(dir, 'HUMAN_ACTIONS.md'))).split('\n')
+    .filter((line) => /^\|/.test(line) && !/^\|\s*:?-+/.test(line))
+    .map((line) => ({ line, cells: line.split('|').slice(1, -1).map((cell) => cell.trim()) }))
+  return rows.filter(({ cells }) => cells.length >= 4 && !/^tarea$/i.test(cells[0]))
+    .map(({ line, cells }) => {
+      const state = (cells[1].match(new RegExp(`^(${HUMAN_ACTION_STATES.join('|')})\\b`, 'i')) || [])[1] || ''
+      return {
+        task: cells[0], state: cells[1], origin: cells[2], action: cells[3],
+        valid: Boolean(state), resolved: state.toLowerCase() === 'resuelta', raw: line,
+      }
+    })
+}
+
 function readWip(dir) {
   const text = read(path.join(dir, 'WIP.md'))
   if (/^status:\s*IDLE/m.test(text)) return null
@@ -189,5 +273,8 @@ function readInbox(dir) {
 }
 
 module.exports = {
-  EPIC_STATES, read, frontmatter, readEpics, readBacklog, readDone, readWip, readInbox,
+  EPIC_STATES, HUMAN_ACTION_STATES, LANES, MILESTONE_HEADING, STOP_REASONS,
+  TASK_LINE, TASK_LINE_ANY_LANE,
+  read, section, withoutComments, frontmatter, readEpics, readBacklog, readDone, readWip,
+  readInbox, readHumanActions,
 }

package/engine/planning/state.js

@@ -0,0 +1,52 @@
+'use strict'
+
+// El estado de un planning ya leído y cuál es la tarea que sigue. Es un nivel por encima de `parser`,
+// que lee un archivo por vez: acá se compone lo que hace falta para decidir, y se aplica la precedencia
+// que fija el protocolo. Vivía en el CLI, donde nadie podía ejercitarlo sin lanzar un proceso.
+
+const P = require('./parser')
+
+function snapshot(root) {
+  const milestones = P.readBacklog(root)
+  return {
+    epics: P.readEpics(root),
+    milestones,
+    done: P.readDone(root),
+    wip: P.readWip(root),
+    inbox: P.readInbox(root),
+    queued: new Set(milestones.flatMap((m) => m.tasks.map((t) => t.slug))),
+  }
+}
+
+
+// Acciones humanas que todavía bloquean: las pendientes y también las mal escritas, porque una fila
+// cuyo estado no se entiende no se puede dar por resuelta. `check` es quien las nombra.
+function pendingHumanActions(root) {
+  return P.readHumanActions(root).filter((row) => !row.resolved)
+    .map((row) => ({ task: row.task, state: row.state, action: row.action }))
+}
+
+
+// Selecciona la tarea que un runner debe ejecutar ahora, con la misma precedencia que el protocolo:
+// WIP activo primero —es el mutex y manda incluso si tiene una acción humana abierta—, si no la
+// primera tarea no terminada y no bloqueada del primer hito.
+function currentTask({ milestones, done, wip }, blockers = []) {
+  const queue = milestones.flatMap((milestone) => milestone.tasks.map((task) => ({ ...task, hito: milestone.slug })))
+  if (wip) {
+    const active = queue.find((task) => task.slug === wip.task)
+      || {
+        slug: wip.task, hito: '', tier: '', cast: { build: '', review: [] },
+        service: wip.service, acceptance: '', epic: '', criteria: [],
+      }
+    return { task: active, skipped: [] }
+  }
+  const blocked = new Set(blockers.map((action) => action.task))
+  const pending = queue.filter((task) => !done.set.has(task.slug))
+  return {
+    task: pending.find((task) => !blocked.has(task.slug)) || null,
+    skipped: pending.filter((task) => blocked.has(task.slug)).map((task) => task.slug),
+  }
+}
+
+
+module.exports = { snapshot, pendingHumanActions, currentTask }

package/flows/system/change-review/FLOW.md

@@ -0,0 +1,64 @@
+# Change Review
+
+Decide si un cambio ya construido se puede entregar. No lo diseña, no lo construye y no lo despliega:
+mira lo que existe y firma, o dice qué falta para poder firmar.
+
+Es el único momento del ciclo donde las disciplinas tienen que poder **discrepar de forma acotada**, y
+por eso es un recorrido y no un cargo. Un revisor solo promedia: mira lo que sabe mirar y aprueba el
+resto por omisión. Acá cada disciplina responde lo suyo y la firma es de quien responde por el cambio.
+
+## Cuándo
+
+Cuando hay un cambio construido esperando entrega. Si todavía no está construido, lo que corresponde es
+`technical-design`; si está roto en producción, `defect-triage`; si ya se entregó y falló,
+`incident-review`.
+
+## Las etapas
+
+| etapa | cargo | pregunta |
+|---|---|---|
+| `scope` | tech-lead | ¿contra qué se revisa, y qué decisiones vigentes lo restringen? |
+| `correctness` | el dueño de la superficie que cambió | ¿hace lo que dice, y qué rompe que nadie nombró? |
+| `evidence` | qa-engineer | ¿qué prueba sostiene cada criterio, y qué está verde sin estar cubierto? |
+| `exposure` | security-engineer | ¿qué queda alcanzable que antes no lo estaba, y por quién? |
+| `operability` | site-reliability-engineer | ¿cómo falla, qué lo muestra y cómo se deshace? |
+| `decide` | tech-lead | el veredicto, con sus tres salidas |
+
+## El veredicto tiene tres salidas
+
+Aprobar; aprobar con lo que hay que corregir antes de entregar; y no poder aprobar. Con dos, las dos
+últimas se confunden: lo que no se resuelve dentro de este cambio gasta igual la vuelta de corrección
+que no lo va a arreglar, y una mejora opinable manda a tocar código por un riesgo que nadie pidió.
+
+Dentro del veredicto, lo que impide entregar se separa de lo que no. Lo primero se corrige; lo segundo
+se registra con su dueño y su condición de reapertura. Una objeción que no se atendió **queda escrita
+con su autor**: promediarla la borra sin resolverla.
+
+## Aprobar sin mirar es el modo de falla
+
+Un veredicto que no enumera qué se inspeccionó no es un veredicto: es una firma. Por eso `scope` cierra
+con la lista literal —archivo, diff, comando con su salida— y `decide` dice qué quedó sin inspeccionar
+y por qué. Un número agregado —cobertura, tests en verde, líneas cambiadas— no sustituye a esa lista:
+mide qué se ejecutó, no qué se atrapó.
+
+## Lo que este recorrido no hace
+
+- **No construye ni corrige.** Devuelve qué hay que corregir; corregirlo es de quien lo construyó.
+- **No despliega ni promueve.** La entrega es una decisión con su propia autorización.
+- **No inventa el criterio.** Si no hay criterio de aceptación contra el cual revisar, eso es lo que
+  informa: revisar contra un criterio supuesto produce una firma que no vale.
+
+## Agentes condicionales
+
+| agente | cuándo |
+|---|---|
+| `backend-engineer` | el cambio toca servicio, contrato o trabajo asíncrono |
+| `frontend-engineer` | toca interfaz web |
+| `mobile-engineer` | toca la aplicación móvil |
+| `database-administrator` | toca esquema, migración o datos en reposo |
+| `privacy-compliance-specialist` | toca datos personales, su base legal o su retención |
+
+La etapa `correctness` la ocupa el dueño de la superficie que cambió; `backend-engineer` es el default
+del contrato y se reemplaza por el que corresponda antes de correr el recorrido.
+
+Validar siempre con `node tools/ops.js flow check change-review` antes de usarlo.