oracle-clue 0.1.0a1__tar.gz

oracle_clue-0.1.0a1/MANIFEST.in

@@ -0,0 +1,4 @@
+include NOTAS-DE-RELEASE.md
+recursive-include docs *.json *.md
+recursive-include tests *.py
+recursive-include tools *.py

oracle_clue-0.1.0a1/NOTAS-DE-RELEASE.md

@@ -0,0 +1,22 @@
+# Oracle Clue 0.1.0a1
+
+Primer corte alpha: contexto reproducible y validación de informes externos. **No incluye revisión automática con IA.**
+
+- `oracle-clue preparar`: diferencia entre commits y contexto explícito, sin cambiar archivos del repositorio ni ejecutar pruebas/proveedores.
+- `oracle-clue validar`: contratos de informe/triage, vigencia de contexto, ids y ubicaciones en el diff.
+- Límites de tamaño y omisiones declaradas de binarios, enlaces y rutas conocidas de credenciales.
+- Wheel con schemas incluidos, sdist y SHA256SUMS.
+
+## Validación
+
+Contratos positivos/negativos, repos Git temporales con defectos sembrados y CLI instalada fuera del checkout. Los resultados exactos quedan en `20261002-212339-prototipar`. La instalación se prueba en Linux. No se afirma evaluación de precisión de IA ni autenticación de personas.
+
+## Publicación manual en PyPI
+
+Los artefactos probados están adjuntos al release y en `dist/`. Verificar SHA256SUMS y publicar con las credenciales del mantenedor:
+
+```bash
+uv publish dist/oracle_clue-0.1.0a1-py3-none-any.whl dist/oracle_clue-0.1.0a1.tar.gz
+```
+
+Este release no implica que ya esté en PyPI. Tras subirlo, comprobar `uvx --from oracle-clue==0.1.0a1 oracle-clue --version` en un entorno limpio.

oracle_clue-0.1.0a1/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: oracle-clue
+Version: 0.1.0a1
+Summary: Contexto reproducible y validación de informes para revisión de cambios Git
+Project-URL: Repositorio, https://github.com/Segtem/oracle-clue
+Project-URL: Issues, https://github.com/Segtem/oracle-clue/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Spanish
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: jsonschema<5,>=4.23
+
+# Oracle Clue — 0.1.0a1 (alpha)
+
+CLI local para preparar contexto reproducible y validar informes externos de revisión de cambios Git. Funciona por separado de Oracle Factory y no requiere una GitHub App ni una dependencia en cada repositorio revisado.
+
+**Este primer corte no llama a un modelo ni encuentra defectos automáticamente.** Entrega el contexto y las comprobaciones de integridad sobre los que se construirá ese revisor. Nunca aprueba, edita código ni fusiona cambios.
+
+## Instalación
+
+La publicación en PyPI queda a cargo del mantenedor. El release de GitHub incluye el wheel probado:
+
+```bash
+uv tool install https://github.com/Segtem/oracle-clue/releases/download/v0.1.0a1/oracle_clue-0.1.0a1-py3-none-any.whl
+oracle-clue --version
+```
+
+Requiere Git y Python >=3.11. Después de publicar esta versión en PyPI, se podrá instalar con `uv tool install oracle-clue==0.1.0a1`.
+
+## Preparar una revisión
+
+Con los cambios confirmados en Git, seleccionar una base que difiera de HEAD. `HEAD~1` compara el último commit con su padre:
+
+```bash
+oracle-clue preparar --repo ./mi-proyecto --base HEAD~1 --salida contexto.json
+```
+
+La salida debe estar fuera de la carpeta revisada y ser un archivo nuevo. Sin `--salida`, el JSON se imprime por stdout. Para incluir archivos de contexto explícitos, agregar `--contexto spec.md --contexto evidencia/pruebas.txt`; sus rutas se resuelven desde la raíz del repo.
+
+El paquete contiene commits base/HEAD, diff por archivo, contenido anterior/actual, rangos por lado y huellas del diff y contexto. Las mismas entradas producen el mismo JSON. `diff_sha256` corresponde a la representación Git raw sin abreviar (rutas, modos e ids de blobs); `context_sha256` abarca además texto, parches, omisiones y archivos seleccionados.
+
+Rechaza cambios versionados sin commit, base inexistente, diff vacío y entradas demasiado grandes. El límite es 200 archivos, 256 KB por archivo y 1 MB para el paquete serializado compacto. Declara omisiones de binarios, enlaces, submódulos y rutas de credenciales conocidas. El filtro no garantiza que otros archivos no contengan secretos; el operador revisa el contexto antes de entregarlo a un proveedor. Clue no envía estos datos a la red.
+
+## Validar un informe externo
+
+Una persona o un proveedor externo produce el informe conforme a [hallazgos.schema.json](https://github.com/Segtem/oracle-clue/blob/v0.1.0a1/docs/hallazgos.schema.json). Los hallazgos conservan el estado `pendiente` y las huellas deben corresponder al paquete:
+
+```bash
+oracle-clue validar informe.json --paquete contexto.json --repo ./mi-proyecto
+```
+
+La CLI vuelve a recolectar el contexto actual y compara el paquete completo; verifica schema, huellas, ids únicos, rutas y rangos de línea del lado correcto del diff. Si hubo omisiones, exige un informe `incompleto` con limitaciones. Un informe vacío nunca equivale a aprobación.
+
+El triage humano se guarda separado, según [triage.schema.json](https://github.com/Segtem/oracle-clue/blob/v0.1.0a1/docs/triage.schema.json). `validar` acepta `--triage decisiones.json` para comprobar el hash exacto del informe, fechas, ids referenciados y decisiones no duplicadas. No crea decisiones ni autentica al revisor o a quien figura como actor.
+
+## Qué sigue
+
+Adaptador de IA de solo lectura, evaluación con defectos sembrados y cambios limpios, e integración opcional con Factory/GitHub. La [arquitectura](https://github.com/Segtem/oracle-clue/blob/v0.1.0a1/docs/arquitectura.md) distingue el flujo previsto del alcance de este alpha. Oracle conserva su función separada: evaluar evidencia contra requisitos acordados.
+
+## Pruebas
+
+```bash
+uv run python -m unittest discover -s tests -v
+```
+
+Las pruebas crean repos temporales, siembran un defecto y verifican que el paquete lo contiene y que un informe fixture apunta al cambio correcto. Comprueban también omisiones, límites, contexto modificado y contratos inválidos. No miden todavía precisión de un modelo.

oracle_clue-0.1.0a1/README.md

@@ -0,0 +1,54 @@
+# Oracle Clue — 0.1.0a1 (alpha)
+
+CLI local para preparar contexto reproducible y validar informes externos de revisión de cambios Git. Funciona por separado de Oracle Factory y no requiere una GitHub App ni una dependencia en cada repositorio revisado.
+
+**Este primer corte no llama a un modelo ni encuentra defectos automáticamente.** Entrega el contexto y las comprobaciones de integridad sobre los que se construirá ese revisor. Nunca aprueba, edita código ni fusiona cambios.
+
+## Instalación
+
+La publicación en PyPI queda a cargo del mantenedor. El release de GitHub incluye el wheel probado:
+
+```bash
+uv tool install https://github.com/Segtem/oracle-clue/releases/download/v0.1.0a1/oracle_clue-0.1.0a1-py3-none-any.whl
+oracle-clue --version
+```
+
+Requiere Git y Python >=3.11. Después de publicar esta versión en PyPI, se podrá instalar con `uv tool install oracle-clue==0.1.0a1`.
+
+## Preparar una revisión
+
+Con los cambios confirmados en Git, seleccionar una base que difiera de HEAD. `HEAD~1` compara el último commit con su padre:
+
+```bash
+oracle-clue preparar --repo ./mi-proyecto --base HEAD~1 --salida contexto.json
+```
+
+La salida debe estar fuera de la carpeta revisada y ser un archivo nuevo. Sin `--salida`, el JSON se imprime por stdout. Para incluir archivos de contexto explícitos, agregar `--contexto spec.md --contexto evidencia/pruebas.txt`; sus rutas se resuelven desde la raíz del repo.
+
+El paquete contiene commits base/HEAD, diff por archivo, contenido anterior/actual, rangos por lado y huellas del diff y contexto. Las mismas entradas producen el mismo JSON. `diff_sha256` corresponde a la representación Git raw sin abreviar (rutas, modos e ids de blobs); `context_sha256` abarca además texto, parches, omisiones y archivos seleccionados.
+
+Rechaza cambios versionados sin commit, base inexistente, diff vacío y entradas demasiado grandes. El límite es 200 archivos, 256 KB por archivo y 1 MB para el paquete serializado compacto. Declara omisiones de binarios, enlaces, submódulos y rutas de credenciales conocidas. El filtro no garantiza que otros archivos no contengan secretos; el operador revisa el contexto antes de entregarlo a un proveedor. Clue no envía estos datos a la red.
+
+## Validar un informe externo
+
+Una persona o un proveedor externo produce el informe conforme a [hallazgos.schema.json](https://github.com/Segtem/oracle-clue/blob/v0.1.0a1/docs/hallazgos.schema.json). Los hallazgos conservan el estado `pendiente` y las huellas deben corresponder al paquete:
+
+```bash
+oracle-clue validar informe.json --paquete contexto.json --repo ./mi-proyecto
+```
+
+La CLI vuelve a recolectar el contexto actual y compara el paquete completo; verifica schema, huellas, ids únicos, rutas y rangos de línea del lado correcto del diff. Si hubo omisiones, exige un informe `incompleto` con limitaciones. Un informe vacío nunca equivale a aprobación.
+
+El triage humano se guarda separado, según [triage.schema.json](https://github.com/Segtem/oracle-clue/blob/v0.1.0a1/docs/triage.schema.json). `validar` acepta `--triage decisiones.json` para comprobar el hash exacto del informe, fechas, ids referenciados y decisiones no duplicadas. No crea decisiones ni autentica al revisor o a quien figura como actor.
+
+## Qué sigue
+
+Adaptador de IA de solo lectura, evaluación con defectos sembrados y cambios limpios, e integración opcional con Factory/GitHub. La [arquitectura](https://github.com/Segtem/oracle-clue/blob/v0.1.0a1/docs/arquitectura.md) distingue el flujo previsto del alcance de este alpha. Oracle conserva su función separada: evaluar evidencia contra requisitos acordados.
+
+## Pruebas
+
+```bash
+uv run python -m unittest discover -s tests -v
+```
+
+Las pruebas crean repos temporales, siembran un defecto y verifican que el paquete lo contiene y que un informe fixture apunta al cambio correcto. Comprueban también omisiones, límites, contexto modificado y contratos inválidos. No miden todavía precisión de un modelo.

oracle_clue-0.1.0a1/docs/arquitectura.md

@@ -0,0 +1,56 @@
+# Arquitectura de Oracle Clue
+
+Estado 0.1.0a1: implementados `preparar` (diff entre commits, con árbol versionado limpio) y `validar` (informe externo y triage opcional). `review`, adaptadores, configuración automática e integración con Factory/GitHub siguen siendo diseño futuro.
+
+## Propósito y frontera
+
+Clue encuentra riesgos concretos introducidos por un cambio y prepara evidencia para el triage humano. El flujo de desarrollo completo pertenece a Oracle Factory. Clue no reemplaza pruebas, revisión humana, Oracle ni al agente que implementa.
+
+## Ejecución
+
+- La herramienta se instala una vez en el entorno del desarrollador o se ejecuta desde su checkout de desarrollo. Los repos revisados no instalan Clue como dependencia obligatoria.
+- Entrada conceptual: `clue review --repo <ruta> --base <ref> [--change <id>] [--provider codex|claude]`. La ruta por defecto será el cwd.
+- La CLI recolecta datos Git y archivos explícitos; invoca el adaptador seleccionado en modo de solo lectura; valida el informe; imprime Markdown y conserva JSON.
+- `.oracle-clue.toml` será opcional y declarará rutas de contexto, comandos de test sugeridos y convenciones locales. Sus comandos requieren aceptación explícita del operador antes de ejecutarse.
+
+## Flujo de análisis
+
+1. Resolver repo, HEAD, base y diff. Rechazar base inexistente y diff vacío; limitar tamaño y excluir binarios/secretos conocidos.
+2. Asociar el cambio con una tarea o paquete OpenSpec por id explícito o metadatos, sin inferir aprobación.
+3. Reunir spec aceptada, archivos cambiados, reglas y evidencia de tests que el operador entregue. El primer prototipo no ejecuta pruebas.
+4. Pedir al proveedor solo defectos plausibles introducidos por el diff. Cada afirmación debe enlazar evidencia y ubicación.
+5. Validar schema, archivo/rango de línea contra el diff y registrar hash de base, HEAD y diff. Invalidar el reporte si alguno cambia.
+6. Dejar cada hallazgo en estado pendiente hasta que una persona lo corrija, descarte con motivo o acepte como riesgo.
+
+## Interfaz de proveedor
+
+Un adaptador recibe un paquete serializado y devuelve JSON conforme al schema. El primer adaptador de prueba puede llamar a `codex exec` en modo read-only; después se compara Claude CLI usando el mismo corpus. Clue no entrega permisos de escritura al proveedor. La revisión no debe fallar silenciosamente a un proveedor alternativo ni esconder su identidad, modelo o errores.
+
+## Esquema de hallazgos
+
+`docs/hallazgos.schema.json` fija el formato. Clases iniciales: bug, seguridad, regresión, discrepancia_con_spec y pregunta. Severidad y confianza son campos separados; una confianza baja no se presenta como hallazgo confirmado. Cada elemento debe incluir título, explicación breve, archivo/líneas, lado base/head del diff, escenario activador, evidencia observable y recomendación de verificación (`verification`). No permitir que el modelo escriba o autoaplique parches.
+
+## Evaluación del prototipo
+
+Preparar cambios de prueba con defectos conocidos y cambios limpios. Registrar defectos sembrados detectados, falsos positivos, ubicaciones correctas y defectos repetidos entre proveedores. No declarar éxito por elocuencia: el criterio es utilidad accionable para una persona.
+
+## Evolución posterior
+
+1. Generador determinista del paquete de revisión y pruebas.
+2. Adaptador de agente local, schema validado y reportes vinculados a hash.
+3. Triage humano persistente en Trackertast/Factory.
+4. Integración GitHub opcional que publica el reporte en PR; sigue sin aprobar ni fusionar automáticamente.
+
+## Frontera entre el modelo y la decisión humana
+
+El adaptador entrega hallazgos pendientes. La CLI completa la identidad del proveedor, modelo (o `null` si no se informa), hashes de commit/diff/contexto y estado de ejecución con datos comprobados; esos metadatos no se toman como afirmaciones del modelo. `review_status: incompleto` requiere explicar limitaciones; un informe vacío o incompleto no equivale a aprobación.
+
+El informe es inmutable. El triage humano vive en `docs/triage.schema.json`, enlazado por el hash del informe, con id de hallazgo, decisión, motivo, actor y fecha. El schema del informe rechaza estados corregido/descartado/riesgo_aceptado. Guardar un nombre de actor no autentica una identidad: esa garantía requiere el canal humano de Factory o GitHub.
+
+La validación futura debe comprobar también lo que JSON Schema no garantiza: ids únicos; `start_line <= end_line`; rutas relativas dentro del checkout; rangos pertenecientes al lado correcto del diff; referencias a hallazgos existentes y decisiones vinculadas al informe vigente. El hash del contexto incluirá spec, reglas y evidencia de pruebas seleccionadas, además del diff. Un contexto cambiado exige otra revisión. La confianza declarada por el modelo no es una probabilidad calibrada.
+
+Ejecutar un agente desde una CLI local no implica inferencia local: Codex/Claude pueden enviar contexto al proveedor que tengan configurado. El operador elige proveedor y alcance de archivos. El paquete debe declarar omisiones y truncamientos; no prometer detección infalible de secretos ni analizar repos completos por defecto.
+
+## Verificación del contrato
+
+`tests/test_contract.py` valida ambos schemas y casos positivos/negativos. Requiere `jsonschema` (solo para pruebas): `uv run --with jsonschema python -m unittest discover -s tests -v`. Los tests de CLI agregan recolección y validación sobre repos temporales. Todavía no existe análisis automático ni evaluación de precisión de un modelo.

oracle_clue-0.1.0a1/docs/hallazgos.schema.json

@@ -0,0 +1,204 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:oracle-clue:review:v1",
+  "title": "Oracle Clue review report",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "repo",
+    "base",
+    "head",
+    "diff_sha256",
+    "provider",
+    "findings",
+    "context_sha256",
+    "review_status",
+    "limitations"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "oracle-clue.review/v1"
+    },
+    "repo": {
+      "type": "string",
+      "minLength": 1
+    },
+    "base": {
+      "type": "string",
+      "pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$"
+    },
+    "head": {
+      "type": "string",
+      "pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$"
+    },
+    "diff_sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "provider": {
+      "type": "object",
+      "required": [
+        "name",
+        "model"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "model": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "kind",
+          "severity",
+          "confidence",
+          "title",
+          "explanation",
+          "location",
+          "trigger",
+          "evidence",
+          "status",
+          "verification"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "kind": {
+            "enum": [
+              "bug",
+              "seguridad",
+              "regresion",
+              "discrepancia_con_spec",
+              "pregunta"
+            ]
+          },
+          "severity": {
+            "enum": [
+              "critica",
+              "alta",
+              "media",
+              "baja",
+              "informativa"
+            ]
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "explanation": {
+            "type": "string",
+            "minLength": 1
+          },
+          "location": {
+            "type": "object",
+            "required": [
+              "file",
+              "start_line",
+              "side",
+              "end_line"
+            ],
+            "properties": {
+              "file": {
+                "type": "string",
+                "minLength": 1
+              },
+              "start_line": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "end_line": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "side": {
+                "enum": [
+                  "base",
+                  "head"
+                ]
+              }
+            },
+            "additionalProperties": false
+          },
+          "trigger": {
+            "type": "string",
+            "minLength": 1
+          },
+          "evidence": {
+            "type": "string",
+            "minLength": 1
+          },
+          "related_requirement": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "status": {
+            "const": "pendiente",
+            "description": "La revisión del modelo nunca contiene decisiones humanas."
+          },
+          "verification": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "context_sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "review_status": {
+      "enum": [
+        "completo",
+        "incompleto"
+      ]
+    },
+    "limitations": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  },
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "review_status": {
+            "const": "incompleto"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "limitations": {
+            "minItems": 1
+          }
+        }
+      }
+    }
+  ]
+}

oracle_clue-0.1.0a1/docs/triage.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:oracle-clue:triage:v1",
+  "title": "Decisiones humanas sobre un informe Oracle Clue",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "report_sha256",
+    "decisions"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "oracle-clue.triage/v1"
+    },
+    "report_sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "finding_id",
+          "status",
+          "reason",
+          "actor",
+          "at"
+        ],
+        "properties": {
+          "finding_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "status": {
+            "enum": [
+              "corregido",
+              "descartado",
+              "riesgo_aceptado"
+            ]
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1
+          },
+          "actor": {
+            "type": "string",
+            "minLength": 1
+          },
+          "at": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

oracle_clue-0.1.0a1/oracle_clue/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0a1"