tracker-cli/backlog/mvp-1.md

Construye un MVP v1 de un sistema local de seguimiento de proyectos personales.

Objetivo:
Crear una herramienta CLI que opere sobre archivos Markdown y YAML para ayudar a seguir proyectos personales con foco en continuidad entre sesiones. El sistema combina Kanban liviano, documentación viva, changelog y bitácora técnica por sesiones.

Restricciones obligatorias:
- usar persistencia en archivos legibles
- Markdown como formato principal
- YAML/JSON simple para metadatos
- sin base de datos
- sin interfaz web
- sin dependencias cloud
- todo debe seguir siendo usable manualmente aunque la CLI no exista
- una sola sesión activa a la vez en v1
- LOG.md append-only
- README.md solo puede modificarse en secciones autogeneradas delimitadas por marcadores AUTOGEN

Stack preferido:
- Python 3.11+
- Typer
- Jinja2
- PyYAML
- GitPython opcional

Estructura del repositorio esperada:
- README.md principal
- pyproject.toml
- tracker.yaml
- paquete tracker/ con cli, services, models, storage, utils y templates
- carpeta projects/
- carpeta tests/
- carpeta examples/

Cada proyecto debe generarse así:
projects/<slug>/
  README.md
  LOG.md
  CHANGELOG.md
  TASKS.md
  sessions/
  docs/
  assets/
  meta/project.yaml

Comandos mínimos a implementar:
- tracker init-project
- tracker list
- tracker show <slug>
- tracker start <slug>
- tracker note <text>
- tracker stop <slug>
- tracker change <slug>
- tracker next <slug>
- tracker review

Comportamiento requerido:

1. init-project
- crea estructura de carpetas
- genera README.md, LOG.md, CHANGELOG.md, TASKS.md y meta/project.yaml desde plantillas
- acepta name, type, tags, repo-path y description

2. list
- muestra nombre, slug, estado, última sesión y próximo paso si existe

3. show <slug>
- muestra estado actual, contexto, último resumen, bloqueos, próximos pasos y última actividad

4. start <slug>
- valida que no exista otra sesión activa
- registra hora de inicio
- crea sesión activa en un archivo tipo .active_session.json
- puede aceptar objective
- muestra contexto reciente

5. note <text>
- agrega nota a la sesión activa
- soporta tipos: work, change, blocker, decision, idea, reference

6. stop <slug>
- registra fin
- calcula duración
- consolida notas
- genera resumen heurístico
- sugiere próximos pasos
- crea archivo detallado en sessions/YYYY-MM-DD_HHMM.md
- actualiza LOG.md
- actualiza README.md en bloques AUTOGEN
- opcionalmente actualiza CHANGELOG.md
- limpia sesión activa

7. change <slug>
- añade una entrada manual al CHANGELOG.md

8. next <slug>
- sugiere próximos pasos por reglas simples, sin IA obligatoria

9. review
- muestra proyectos activos, últimas sesiones, bloqueos abiertos y proyectos sin actividad reciente

Modelo mínimo:

Proyecto:
- id
- name
- slug
- description
- type
- status
- tags
- root_path
- repo_path
- created_at
- updated_at
- last_session_at

Sesión:
- id
- project_slug
- started_at
- ended_at
- duration_minutes
- objective
- summary
- work_done
- changes
- decisions
- blockers
- next_steps
- references
- raw_notes

Cambio:
- date
- type
- title
- impact
- references

Valores sugeridos de type:
- code
- homelab
- automation
- agent
- research
- misc

Valores sugeridos de status:
- inbox
- next
- active
- blocked
- waiting
- done
- archived

README.md del proyecto debe incluir:
- nombre
- descripción
- objetivo
- estado actual
- contexto actual
- stack / herramientas
- arquitectura breve
- decisiones técnicas
- riesgos / bloqueos
- próximos pasos
- últimas sesiones

Usa bloques delimitados, por ejemplo:
<!-- AUTOGEN:STATUS_START -->
...
<!-- AUTOGEN:STATUS_END -->

LOG.md debe ser append-only y usar entradas como:
## 2026-03-23 10:00–11:20
**Objetivo**
...
**Trabajo realizado**
- ...
**Cambios relevantes**
- ...
**Bloqueos**
- ...
**Decisiones**
- ...
**Próximos pasos**
- ...
**Resumen**
...

CHANGELOG.md debe registrar solo cambios relevantes:
- code
- infra
- config
- docs
- automation
- decision

TASKS.md debe tener secciones:
- Inbox
- Próximo
- En curso
- Bloqueado
- En espera
- Hecho

Heurísticas mínimas:
- si hay bloqueos abiertos, priorizar destrabar
- si hubo cambios sin validación, sugerir validar
- si hubo trabajo parcial, sugerir cerrar el hilo abierto
- si no hubo avances, sugerir redefinir objetivo
- si hubo commits recientes no documentados, sugerir registrarlos

Integración Git:
- opcional
- leer commits recientes si repo_path existe
- no hacer commit, push ni cambios de ramas

Requisitos de calidad:
- código modular
- mensajes de error claros
- paths multiplataforma
- UTF-8
- tests básicos del flujo principal

Entregables:
- estructura completa del repositorio
- CLI funcional
- plantillas base
- README principal
- ejemplos de uso
- tests básicos
- proyecto demo

Prioriza claridad, mantenibilidad y bajo acoplamiento.

Además:
- implementa primero la estructura y los comandos base
- evita sobreingeniería
- usa funciones pequeñas y testeables
- separa claramente CLI, lógica de dominio y persistencia
- no escondas datos importantes en formatos opacos
- añade ejemplos de salida de comandos
- incluye un proyecto demo ya generado
- incluye tests del flujo init-project → start → note → stop → show