Limpieza de superficie del CLI: solapamientos build/networks, curación, export (de la sesión de QA 0.8)

[complexluise]

Surgió del uso hands-on del CLI 0.8 en una sesión de QA/dogfooding (nota docs/Notas/19-qa-cli-superficie-limites.md). Es debate de dirección, no trabajo decidido — abro para discutir antes de filar una limpieza. Los bugs accionables de esa sesión ya tienen issue (#124 API key, #126 trazabilidad PRISMA, #125 warning uv); esto es sobre el diseño de la superficie de comandos.

El CLI tiene 20 subcomandos. El núcleo conceptual es ingestar → curar → enriquecer → proyectar redes → exportar, + inspección. Usándolo de punta a punta aparecen algunos solapamientos que conviene debatir:

Solapamiento	Detalle	Idea a debatir
build vs networks	Ambos construyen redes. build = quick (5 redes default); networks --spec = declarativo YAML. Dos comandos para lo mismo confunde.	¿Unificar en b2g build (sin spec → quick) + b2g build --spec (declarativo)?
accept/reject vs curate --from-csv	Curación puntual por --ids vs lote por CSV. Justificado, pero son 3 puertas de curación + el alias deprecado --all.	¿Agrupar bajo b2g curate {dump,import,accept,reject}?
export vs salida de build	build ya escribe network.graphml; export re-serializa. Útil para CSV/re-export, pero solapado para GraphML.	Aclarar que export es para formatos adicionales, no un paso obligatorio.
status vs inspect	Ambos muestran estado (lazo+conteos vs manifest/paper).	¿inspect sin args = lo que hoy da status?
monitor vs chain forward	Ambos buscan citantes nuevos en OpenAlex.	Afinar la ayuda para distinguirlos.
--all vs --scope all (curate)	--all es alias deprecado.	Quitar en limpieza.

Criterio que NO hay que romper: la naturaleza agente-native (envelope --json consistente, scriptabilidad). Cualquier consolidación tiene que preservar eso.

Preguntas abiertas:

1. ¿Cuáles de estas consolidaciones valen la pena vs. cuáles son cosmética?
2. ¿Alguna rompería scripts/agentes que ya dependen de la superficie actual?
3. ¿Conviene un grupo de comandos (curate ...) o aliases, o dejarlo plano?

Si cuaja una dirección, se baja a issue(s) de limpieza.

[complexluise]

Propuesta de convergencia: superficie agents-first para 0.10.0 (más es menos)

(a) Encuadre

Esta propuesta cierra el debate de #127 y AMPLÍA su alcance: además de resolver los 6 solapamientos listados arriba, incorpora la "mitad faltante" del CLI (la capa de lectura/análisis) detectada en las notas de sesión 14/15/18, y el diagnóstico de "redes vacías con cara de éxito" de la nota 20.

Objetivo del 0.10.0: que un agente LLM decente pueda correr el ciclo completo en one-shot. Principio rector: la superficie ES el ciclo de investigación; status es el mapa que el agente lee para saber cuál es el próximo comando.

(b) La superficie propuesta

Son 10 verbos que mapean el ciclo INIT → SEED → CHAIN → CURATE → BUILD → READ → EXPORT/SNAPSHOT, con STATUS transversal:

Verbo	Qué hace	Absorbe / nota
b2g init	workspace; declara host de red OpenAlex y muestra el primer comando	folds fricciones de dependencia de red y el alias bib2graph≠b2g
b2g seed --from-bib FILE | --from-equation Q	dos puertas de ingesta; --resolve DOIs→OpenAlex (BibTeX primera clase); --email en ambas; --limit N	unifica las puertas de entrada
b2g chain --back --forward	forrajeo con caps + filtros sensatos por defecto + progreso	absorbe monitor como modo incremental (--since)
b2g curate {dump,apply,accept,reject,filter}	dump/apply CSV, accept/reject por ids, filter PRISMA con criterio legible	absorbe accept/reject/filter y quita el alias --all
b2g build [--scope all|accepted|seeds] [--spec YAML] [--min-weight N]	construye redes; default corre SIN curar (one-shot); warning+diagnóstico si una red sale vacía	absorbe networks vía --spec
b2g read {list,stats,top,show}	list/grep corpus, stats --group-by, top = centrales + co-citación con título (salida de investigación, NUEVO), show --id	absorbe inspect --id
b2g export / b2g snapshot	formatos extra / snapshot reproducible	clarifica export vs build
b2g status	FSM + readiness + next_best_action + dependencies + diagnóstico red-vacía	absorbe inspect sin args y el "doctor" (SIN comando nuevo)
b2g validate	se mantiene	—

(c) Historia one-shot

b2g init mi-investigacion
b2g seed --from-bib refs.bib --resolve --email yo@ejemplo.org
b2g chain --back --forward
b2g build --scope all
b2g read top --json
b2g snapshot
# en cada punto, `b2g status --json` dice cuál es el próximo paso (next_best_action)

(d) Invariantes respetados

Es una reorganización SEMÁNTICA, no una ruptura del contrato:

• El envelope schema="1", los exit codes y la FSM del lazo se preservan (ADR 0021 / 0016 / 0010).
• readiness y el diagnóstico de red vacía entran como campos ADITIVOS de status (no comando nuevo → respeta el invariante de subcomandos del ADR 0021).
• Stdout puro en --json (enmienda menor a 0021).
• --resolve ya estaba previsto por el ADR 0035.

(e) Decisiones a graduar a ADR (pido confirmación del PO en el hilo)

1. ¿Se adopta el set consolidado de 10 verbos como contrato de superficie 0.10.0 (reemplaza/enmienda los 12 subcomandos del ADR 0021)?
2. ¿curate y read como grupos de subcomandos (noun-verb) es el patrón, o se prefieren verbos planos?
3. ¿monitor se absorbe en chain --since o se mantiene separado?
4. Alias de retrocompat para los comandos que se consolidan (build/networks, accept/reject) durante una ventana de deprecación: ¿sí/no?

(f) Referencias

• Notas de sesión: docs/Notas/14, 15, 18, 19, 20.
• ADRs: 0010 / 0016 / 0021 / 0029 / 0035 / 0036.
• Issues relacionados: feat(skills): skill instalable de opencode/claude code que automatice el flujo E2E de bib2graph #76 (skill E2E, depende de readiness), docs: overhaul de documentación de usuario (tono producto, separar de doc interna) #132 (docs usuario).

---

Si el PO confirma (a)–(e), esto se gradúa a ADR de superficie y arranca la implementación de 0.10.0.

[complexluise]

Seguimiento del PO: dos adiciones diferidas (el ADR de superficie sale tal cual)

Confirmo la propuesta de convergencia (a)–(e): el set de 10 verbos se gradúa a ADR de superficie 0.10.0 como está. Dejo registradas dos afinadas que surgieron al pensar la superficie contra el ciclo de investigación (nota 05) y la AX del agente (nota 20). No las foldeo en este ADR — las difiero conscientemente a seguimiento para no demorar la superficie:

• (e.5) status como modelo git status — preview "qué se materializa si actúo ahora". Hoy la propuesta pone el diagnóstico de red-vacía como warning al correr build (después). La afinada lo mueve a status (antes): el equivalente al staged vs unstaged. status no diría solo "build disponible", sino "build produciría: citación VACÍA 0/15, keyword OK 15/15" — un preview por-red dentro de status. (Generaliza al build lo que feat/chain-preview/feat(cli): preview de crecimiento del chaining antes del fetch — historia B2 #89 ya hace para chain.)
• (e.6) Maturity-stamp del one-shot. El artefacto del one-shot (build/snapshot/read top) lleva un bloque maturity/caveats en el --json: "sin curar, scope=all, no saturado, 2 redes vacías por falta de source_id." Es status aplicado a la salida, y vom Brocke/PRISMA hecho self-description: el resultado es honesto sobre su propia incompletitud. Hace explícito que el one-shot es un borrador sin pulir (valioso como primera iteración, pero etiquetado como tal).

Ambas son campos aditivos del mismo género que el resto (no rompen el envelope ni la FSM). Quedan acá como deuda consciente; se promueven a issue vía /abrir-issue cuando se tomen.

[complexluise]

Graduada a ADR 0037 ✅

La decisión de superficie (a)–(d) se graduó a ADR 0037 — Superficie CLI 0.10.0: 10 verbos agents-first (enmienda a 0021; envelope schema="1"/exit/FSM intactos). PR a dev: #150.

Las dos afinadas diferidas (e.5 preview por-red en status, e.6 maturity-stamp del one-shot) quedan como follow-up consciente en discussioncomment-17450871 — entran por su propio ADR/issue cuando se tomen.

Cierro el debate de superficie acá cuando #150 mergee a dev.

[complexluise]

Corrección: e.5 y e.6 ya NO se difieren — entran a 0037

Decisión del PO (2026-06-26): las dos afinadas que arriba quedaban como follow-up se incorporan al ADR 0037 (PR #150), no se posponen.

• (e) preview por-red en status — el diagnóstico de red-vacía pasa de build-time a status-time (modelo git status staged/unstaged): status dice, por red, si build saldría vacío y por qué, antes de actuar. Cierra de raíz la trampa de la Nota 20.
• (f) maturity-stamp del one-shot — los artefactos (build/snapshot/read) llevan un bloque maturity aditivo que los autodeclara borrador sin pulir.

Ambas son campos aditivos (schema="1" intacto). El comentario discussioncomment-17450871 queda como historia.

[complexluise]

Mergeado en #150 (ADR 0037 en dev). El debate de superficie queda resuelto; la implementación 0.10.0 arranca. Cierro.