Docs/v2 GitHub tracking

.github/ISSUE_TEMPLATE/task.md

@@ -0,0 +1,26 @@
+---
+name: Tarea de roadmap
+about: Tarea de una versión del roadmap de ResearchOS
+title: "[T##] "
+labels: ''
+---
+
+## Objetivo
+
+## Contexto
+
+## Criterios de aceptación
+- [ ]
+
+## Capas afectadas
+
+## Decisiones a documentar
+
+## Objetivo de aprendizaje
+
+## Fuera de alcance
+
+## Estimación
+**h**
+
+## Depende de

CLAUDE.md

@@ -152,3 +152,19 @@ Two rules that always apply, regardless of the skill being loaded:
    `<proposed message>`. Shall I proceed?"
 2. Commit messages are written in English, even though code comments and
    project docs may be in Spanish.
+
+
+---
+
+## Weekly Work Cycle (GitHub Project)
+
+Given that the repo already has a Project and associated Issues on GitHub, the weekly workflow is as follows:
+
+- Monday. Choose the issue for the week, move it to “In Progress” in the Project, and enter an estimate (h). Create a branch with a name matching the issue.
+
+- Monday through Thursday. Make commits referencing the issue with (#N). Acceptance criteria are checked off as they’re met—this gives you visible progress without having to write reports.
+Upon closing. Create a pull request with “Closes #N” in the description; merge it, and the issue closes automatically, advancing the milestone bar. Enter the Actual (h).
+
+- Friday. The closed issues from the week serve as input for generating the question bank. The “interview-bank” skill reads the git log; if the commits reference issues, the context it receives is richer.
+
+And the metric that really matters in the long run isn’t the milestone bar: it’s the ratio of Estimate to cumulative Actual. In three months, you’ll know whether you systematically underestimate infrastructure work, refactoring, or integration with external APIs. That data stays with you for the rest of your career, and almost no one has it because almost no one measures it.

docs/learnings.md

@@ -348,3 +348,63 @@ Regla simple para ResearchOS:
 - Tercer error mecánico de escritura de Python en una semana (los anteriores: `:` en vez de `=` en una asignación, `self` omitido en firmas de Protocol). No son conceptuales — es un hueco de automatismo que se cierra con repetición.
 
 ---
+
+**Fecha:** 13/08/2026
+
+### ¿Qué aprendí?
+
+- **La razón de ser de un grafo no es el estado — es poder volver atrás.** Le
+  pregunté a mi tutor qué gana un grafo sobre mi pipeline lineal
+  (`retrieve → generate`) y mi primera respuesta se quedó en el estado
+  explícito. La corrección: el estado es el *mecanismo* que hace que un ciclo
+  signifique algo (sin estado compartido, una iteración no puede acumular lo
+  que aprendió la anterior), pero el *fin* es poder bifurcar (conditional
+  edge — ir a arXiv si la recuperación local trajo poco, ir directo a
+  generar si trajo suficiente, mi T19) y poder ciclar (volver a un nodo
+  anterior — recuperar, evaluar que es malo, reescribir la query, recuperar
+  de nuevo, mi T22). Una cadena de funciones no puede hacer ninguna de las
+  dos: va en una sola dirección.
+- **"No puedo conocer el estado intermedio" es falso — es incompleto.** Dije
+  que con mi pipeline lineal no podía saber qué pasó en cada paso. Sí puedo:
+  un `logger.debug` después del retrieval, o devolver los documentos junto
+  con la respuesta. La diferencia real no es posible-vs-imposible, es
+  construcción-vs-instrumentación: en un grafo la inspeccionabilidad viene
+  gratis porque cada nodo ya es una unidad nombrada con entrada y salida
+  declaradas — cuando conecte Langfuse en V3 no voy a instrumentar nada, las
+  trazas van a salir solas de la estructura. Con funciones encadenadas, cada
+  punto de observación lo tengo que agregar yo, y se me puede olvidar.
+- **Tampoco es cierto que el grafo me dé el resultado final antes.** También
+  hay que ejecutarlo completo para tener la respuesta. Lo que cambia no es
+  *cuándo* conozco el final, es que conozco los pasos intermedios sin
+  esfuerzo extra.
+- **Para mi pipeline de hoy (dos pasos, sin ramas ni ciclos), LangGraph es
+  sobrecosto puro.** Un DAG lineal de dos nodos no necesita un grafo — para
+  eso alcanza encadenar dos funciones. La justificación de T18 no está en
+  T18 mismo: está en que T19 (rama condicional) y T22 (ciclo de reescritura
+  de query) no se pueden construir sin el grafo ya montado. Es
+  infraestructura que se paga adelante, no un beneficio inmediato.
+- **LangGraph es orquestación de bajo nivel; LangChain es construcción de
+  agentes de alto nivel** (modelos + tools ya integrados, con
+  `create_agent`). El cambio de LangGraph 0.x a 1.x deprecó
+  `create_react_agent` en favor de ese `create_agent` de LangChain, que por
+  debajo se apoya en LangGraph para control de flujo, human-in-the-loop y
+  persistencia de estado.
+- **El human-in-the-loop depende de que el estado sea explícito y
+  persistente.** Si el flujo fuera una cadena de llamadas continua, un
+  humano solo se entera del resultado al final (ej. un correo ya borrado
+  por error, marcado incorrectamente como spam). Con estado explícito y una
+  interrupción que lo persiste, el flujo se puede pausar, un humano corrige
+  el estado ("este correo no es spam"), y el agente continúa desde ahí sin
+  perder lo ya hecho ni reiniciar el proceso completo.
+- Versiones fijadas hoy para arrancar V2: `langgraph==1.2.11`,
+  `langchain==1.3.15`, `langchain-anthropic==1.5.6`,
+  `langgraph-checkpoint==4.2.0`.
+
+### ¿Qué no entendí bien?
+
+- El mecanismo concreto de una interrupción de LangGraph que persista el
+  estado para que un humano intervenga y el flujo continúe después — sé que
+  existe (`AgentState`/`AgentStatePydantic` y objetos de human-in-the-loop
+  cambiaron en la migración 0.x → 1.x) pero no verifiqué la API real todavía.
+
+---

docs/work_log.md

@@ -259,3 +259,31 @@
 - V1 real cerrada tras el merge — arrancar V2 (T18: LangGraph fundamentals)
 
 ---
+
+## 2026-08-13
+
+### Trabajo desarrollado
+- Fix real de T14: `_download_pdf` crea el directorio padre antes de escribir
+  (`ingestion_service.py`), y `test_extract_text_pdf` parcha `PAPERS_DIR` a
+  `tmp_path` para no ensuciar el repo — verificado en un clon fresco real,
+  no solo en el working copy (`9491967`, merge PR#5)
+- `ROADMAP.md` corregido: T14 tenía fecha de cierre falsa (12/08), quedó con
+  la fecha real (13/08) y la nota de qué faltaba; T17 (merge a `main`) marcado
+- Tag `v1.0.0` re-apuntado al commit de merge de PR#5 — V1 real cerrada
+- Tracking de V2 configurado en GitHub: 11 labels, milestone "V2 — Agente
+  LangGraph + Briefing matutino" (vence 02/10), `.github/ISSUE_TEMPLATE/task.md`,
+  y los 7 issues T18–T24 con estimaciones, dependencias y labels
+- Estudio de LangGraph: notebook de práctica, dependencias agregadas
+  (`langgraph`, `langchain`, `langchain-anthropic`), y entrada en
+  `learnings.md` sobre por qué un grafo aporta (bifurcaciones y ciclos, no
+  el estado) — corregida una confusión conceptual real en la conversación
+  con el tutor
+- `CLAUDE.md` actualizado con el ciclo semanal de trabajo vía GitHub Project
+
+### Próximos pasos
+- Abrir PR y mergear `docs/v2-github-tracking` a `main`
+- Arrancar T18 (LangGraph fundamentals) el lunes 17/08
+- Mañana (14/08, viernes): agregar la pregunta de grafo-vs-pipeline al banco
+  de preguntas en el ritual normal
+
+---