Factory,
desde cero.

ANTES DE EMPEZAR

Un ejemplo pequeño, un flujo completo.

Vamos a comprobar una función que acepta títulos con texto y rechaza títulos vacíos o con espacios. El código ya viene escrito. No vamos a crear una pantalla, guardar notas ni publicar una app. El objetivo es entender cómo Factory registra el acuerdo, la revisión y el juicio hasta cerrar una tarea local.

Una terminal es una ventana para escribir comandos: PowerShell desde Inicio en Windows, Terminal en macOS o la aplicación Terminal en Linux. Pegá una línea, presioná Enter y esperá a que termine. Si aparece un error, resolvelo antes de avanzar. Todos los comandos del proyecto se ejecutan desde la misma carpeta.

uv instala Python y las herramientas. PyPI es el catálogo de paquetes. Git conserva versiones de los archivos. Un editor de texto plano permite escribir código y documentos: podés instalar Visual Studio Code. No uses Word.

En el editor elegí Archivo → Abrir carpeta y seleccioná la carpeta del proyecto que crearás en el paso 2. Su panel de archivos permite abrir cualquier extensión, incluso .oracle y .requisito. Para crear o editar un archivo, elegí Nuevo archivo o hacé clic sobre el archivo; guardá con Ctrl+S (Cmd+S en macOS), como texto UTF-8.

En Windows activá “Extensiones de nombre de archivo” en el Explorador para evitar spec.md.txt. Las rutas con un punto inicial, como .factory-demo o .gitignore, pueden estar ocultas: usá el panel del editor; en el Explorador activá elementos ocultos, en Finder presioná Cmd+Shift+. y en gestores de Linux suele ser Ctrl+H.

Los bloques con “Copiar” son comandos de terminal, salvo cuando se indica que son contenido para un archivo. Las frases de confirmación son respuestas a una pregunta de Factory: no las ejecutes como comandos. Más adelante vas a pegar el id de tu cambio y el id del requisito para completar los comandos de esta página. Sin JavaScript, reemplazá a mano ID_DEL_CAMBIO e ID_DEL_REQUISITO por esos identificadores completos.

Podés seguir los comandos sin experiencia, pero aprobar una revisión de código exige criterio técnico. Si no podés evaluar el programa, pedí ayuda a alguien que sí pueda. La guía se reprodujo en Linux; Windows y macOS se revisaron por sus comandos, sin ejecución completa en esos sistemas. Todavía falta un piloto con una persona principiante.

PASO 01

Instalá las herramientas.

Instalá Git para tu sistema y el editor. Después instalá uv con el comando de tu sistema, tomado de su guía oficial.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

wget -qO- https://astral.sh/uv/install.sh | sh

Cerrá y volvé a abrir la terminal. Estos comandos deben mostrar una versión:

uv --version
git --version

Instalá Python y el kit. Instalamos el wheel de la versión 0.1.0a3 desde el release oficial en GitHub (la subida a PyPI está pendiente; no instales la 0.1.0a2 de PyPI porque no incluye el inicio guiado ni el comando medir). uv tool install crea un entorno separado; --with-executables-from permite usar también los comandos de Oracle y Oracle Task.

uv python install 3.13
uv tool install --python 3.13 --with-executables-from oracle-metalenguaje,oracle-task https://github.com/Segtem/oracle-factory/releases/download/v0.1.0a3/oracle_factory-0.1.0a3-py3-none-any.whl
uv tool update-shell

Volvé a abrir la terminal y comprobá las versiones. En una instalación nueva esperamos 0.1.0a3, 0.38.1 y 0.2.0, respectivamente:

oracle-factory --version
oracle --version
tasks --version

El paquete oracle-metalenguaje instala oracle; oracle-task instala oracle-task y el alias tasks. Enlaces: Release Factory 0.1.0a3, Oracle en PyPI y Oracle Task en PyPI.

PASO 02

Prepará un proyecto nuevo.

Creá una carpeta vacía desde tu terminal. No hace falta clonar Factory:

mkdir mi-primer-proyecto
cd mi-primer-proyecto
git init
oracle-factory init

Si Git avisa sobre el nombre de la rama inicial, podés continuar. oracle-factory init inicializa Oracle, Oracle Task y OpenSpec, y añade automáticamente las exclusiones en .gitignore para .factory-demo/, __pycache__/ y *.py[cod] sin sobrescribir tu configuración previa. Los mensajes siguientes provienen de Factory.

Abrí mi-primer-proyecto en el editor. Verás oracle.json, tareas/, openspec/changes/, catalogos/ y .gitignore. Podés abrir .gitignore para verificar que contenga esas exclusiones de archivos generados y temporales:

.factory-demo/
__pycache__/
*.py[cod]

Ya no necesitás copiar archivos de ejemplo manualmente: en el paso siguiente, el comando de inicio guiado preparará todo el material del ejemplo automáticamente.

oracle-factory --help

La ayuda muestra los subcomandos disponibles. Factory usa la carpeta actual; para otro proyecto, la opción --proyecto ruta-al-proyecto va antes del subcomando.

PASO 03

Abrí tu primer cambio guiado.

oracle-factory nuevo --con-ejemplo notas "Comprobar el título de una nota"

El comando infiere la capacidad notas, copia el ejemplo completo a examples/notas, copia la propuesta y la especificación a la carpeta del nuevo cambio, y copia las reglas a catalogos/. Comprueba todos los destinos antes de crear la tarea y rechaza destinos existentes sin sobrescribir ningún archivo.

Factory imprime el id del cambio y sus rutas exactas. Copialo completo, sin inventarlo ni abreviarlo. Si abrís una terminal nueva o perdés el id, recuperalo con:

oracle-factory listar

oracle-factory listar recupera únicamente los cambios de Factory con su ID completo y su fase actual, sin crear tareas duplicadas ni adivinarlos.

Tu tarea vive en tareas/ID_DEL_CAMBIO/TAREA.md y el paquete del cambio en openspec/changes/ID_DEL_CAMBIO/.

PASO 04

Leé, acordá y elegí las medidas.

El comando anterior ya preparó los documentos en el cambio y las reglas en catalogos/ sin requerir copias manuales. En el editor abrí openspec/changes/ID_DEL_CAMBIO/proposal.md y openspec/changes/ID_DEL_CAMBIO/specs/notas/spec.md. La promesa exige rechazar títulos vacíos o con espacios y aceptar títulos con texto, descrita en tres escenarios. Si eso representa lo acordado, ejecutá:

oracle-factory aprobar-spec ID_DEL_CAMBIO

Respuesta al pedido de confirmación, no un comando: APROBAR ESPECIFICACION ID_DEL_CAMBIO
Escribila cuando la terminal la pida, después de revisar los documentos. Si cancelás o la frase no coincide, repetí el comando para volver a intentarlo.

Ahora importá el requisito a Oracle:

oracle-factory importar ID_DEL_CAMBIO

Oracle crea un archivo .requisito en requisitos/ e imprime el identificador generado (con un dominio aislado propio de este cambio; copiá el id completo de la salida, sin reconstruirlo). Al principio el requisito nace SIN MEDIR.

Consultá los requisitos importados y las medidas disponibles en el catálogo con:

oracle-factory medir ID_DEL_CAMBIO --listar

medir --listar muestra el requisito completo, su texto, las fuentes y las medidas efectivas del catálogo con sus límites, sin modificar ningún archivo. Copiá el identificador del requisito:

Asociá explícitamente las medidas al requisito sin editar indentación a mano:

oracle-factory medir ID_DEL_CAMBIO --requisito ID_DEL_REQUISITO --medida notas.casos_ejecutados --medida notas.resultados --quitar-sin-medir

Por defecto, medir conserva sin_medir; para retirarlo se exige --quitar-sin-medir explícito. Si solo quisieras comprobar una parte del alcance, podés usar --sin-medir "alcance pendiente" para registrar cobertura parcial con un motivo.

La especificación aprobada debe estar vigente. Si indicás una medida que no existe o un requisito de otro cambio, la asociación se rechaza sin alterar ningún archivo. Si en el futuro modificás las medidas asociadas, la revisión y el veredicto de Oracle previos quedan invalidados automáticamente.

Enlazar medidas no prueba pertinencia ni cumplimiento: la existencia de una regla en el catálogo solo define qué observará Oracle; es una decisión humana evaluar si esas medidas realmente demuestran la promesa acordada.

Si deseás inspeccionar el archivo generado en tu editor, podés abrir requisitos/ID_DEL_REQUISITO.requisito. El comando ya escribió una asociación válida; no hace falta editar el archivo a mano.

Comprobá el enlace con Oracle:

oracle cobertura --proyecto .

Esperamos 1 requisito medido, 0 sin medir, con ✓. Esa marca informa un enlace: todavía no demuestra que el programa cumpla. Antes de quitar el límite, leé ambas reglas y el sensor. Una regla exige tres observaciones, la otra cero resultados fallidos; el número por sí solo no demuestra que sean tres casos distintos. Los casos de este ejemplo son vacío, espacios y texto válido. El juicio queda limitado a esas observaciones.

PASO 05

Probá el programa y registrá lo que pasó.

Leé examples/notas/notas.py, test_notas.py y sensor.py en el editor. Las pruebas y el sensor se ejecutan por fuera de Factory. Ejecutá primero los tests y después el sensor sobre la versión a evaluar:

uv run --no-project --python 3.13 python -m unittest discover -s examples/notas -p "test_*.py" -v

uv run --no-project --python 3.13 python examples/notas/sensor.py --salida .factory-demo/hechos.json

Esperamos Ran 3 tests, OK y el archivo .factory-demo/hechos.json con tres observaciones. El sensor ejecuta la función y compara cada resultado con lo esperado. Factory juzgará ese JSON, sin ejecutar por sí misma el sensor ni las pruebas.

Guardá la versión antes de revisarla. Un commit es una versión registrada de los archivos elegidos. Configurá tu identidad de Git para esta carpeta si aún no lo hiciste; esos datos quedan en el historial:

git config user.name "Tu nombre"
git config user.email "tu-correo@example.com"

git add .
git commit -m "ID_DEL_CAMBIO: ejemplo de notas"

Terminá los cambios al código, documentos y medidas antes de registrar la revisión. Crear otro commit posterior cambia la versión que Factory compara.

PASO 06

Revisá el cambio y dejá un informe real.

La revisión debe comprobar código, pruebas, sensor y medidas contra el acuerdo. Si no entendés el código, pedí a una persona con competencia técnica que lo revise. Una revisión con herramientas externas o IA puede aportar sugerencias, pero una persona debe evaluar las conclusiones. Factory y Clue no hacen ese análisis automáticamente.

El paso anterior generó .factory-demo/. Creá dentro un archivo review.md con tu editor. Este bloque es contenido inicial para ese archivo: completá todos los campos pendientes con lo que realmente se revisó; no es una aprobación fingida:

# Revisión del cambio

Revisor: PENDIENTE
Versión revisada (git rev-parse HEAD): PENDIENTE
Archivos y casos revisados: PENDIENTE
Resultados de pruebas y sensor: PENDIENTE
Hallazgos y decisión motivada para cada uno: PENDIENTE
Hallazgos abiertos: PENDIENTE
Límites de la revisión: PENDIENTE
Conclusión: PENDIENTE

Para obtener el identificador exacto del commit:

git rev-parse HEAD

Si quedan problemas, corregilos, repetí tests y sensor, y creá un nuevo commit. Solo cuando el informe esté completo, una persona apruebe y no queden hallazgos abiertos, registrá:

oracle-factory revision ID_DEL_CAMBIO --informe .factory-demo/review.md --revisor "Tu nombre" --decision aprobar --hallazgos-abiertos 0

Respuesta al pedido de confirmación, no un comando: REGISTRAR REVISION ID_DEL_CAMBIO
Escribila cuando la terminal la pida, después de revisar los documentos. Si cancelás o la frase no coincide, repetí el comando para volver a intentarlo.

Sustituí “Tu nombre” por quien revisó. Factory verifica que el informe exista y no esté vacío, guarda su huella y vincula el contexto de Git. No lee el contenido para verificar las conclusiones: declarar cero no sustituye resolver los problemas ni demuestra ausencia de errores.

PASO 07

Evaluá la evidencia y decidí el cierre.

oracle-factory juzgar ID_DEL_CAMBIO --con .factory-demo/hechos.json

oracle-factory estado ID_DEL_CAMBIO

El juicio debe confirmar el requisito y el estado debe informar que no quedan pendientes bloqueantes. Un verde aquí significa que las medidas aceptaron tres observaciones sin resultados fallidos. No garantiza que sean tres casos distintos, que los hechos provengan del código actual o que todo el producto esté bien.

Factory guarda huellas del producto, informe y hechos para detectar cambios posteriores. No certifica cómo se produjo el JSON. Comprobá que ejecutaste el sensor para la versión revisada; si dudás, renová la evidencia y el juicio antes de cerrar.

oracle-factory cerrar ID_DEL_CAMBIO

Respuesta al pedido de confirmación, no un comando: CERRAR ID_DEL_CAMBIO
Escribila cuando la terminal la pida, después de revisar los documentos. Si cancelás o la frase no coincide, repetí el comando para volver a intentarlo.

oracle-factory estado ID_DEL_CAMBIO

Esperamos Fase: cerrada y la tarea cerrada en Oracle Task. No creamos un release, desplegamos una app ni enviamos commits a GitHub. Completamos un cambio local trazable con acuerdos y evidencias humanas.

SI ALGO NO FUNCIONA

Retomá el paso que necesita atención.