82a358f18d
ontoref-derive: #[onto_mcp_tool] attribute macro registers MCP tool unit-structs in
the catalog at link time via inventory::submit!; annotated item is emitted unchanged,
ToolBase/AsyncTool impls stay on the struct. All 34 tools migrated from manual wiring
(net +5: ontoref_list_projects, ontoref_search, ontoref_describe,
ontoref_list_ontology_extensions, ontoref_get_ontology_extension).
validate modes (ADR-018): reads level_hierarchy from workflow.ncl and checks every
.ncl mode for level declared, strategy declared, delegate chain coherent, compose
extends valid. mode resolve <id> shows which hierarchy level handles a mode and why.
--self-test generates synthetic fixtures in a temp dir for CI smoke-testing.
validate run-cargo: two-step Cargo.toml resolution — workspace layout first
(crates/<check.crate>/Cargo.toml), single-crate fallback by package name or repo
basename. Lets the same ADR constraint shape apply to workspace and single-crate repos.
ontology/schemas/manifest.ncl: registry_topology_type contract — multi-registry
coordination, push targets, participant scopes, per-namespace capability.
reflection/requirements/base.ncl: oras ≥1.2.0, cosign ≥2.0.0, sops ≥3.9.0, age
≥1.1.0, restic declared as Hard/Soft requirements with version_min, check_cmd, and
install_hint (ADR-017 toolchain surface).
ADR-019: per-file recipient routing for tenant isolation without multi-vault. Schema
additions: sops.recipient_groups + sops.recipient_rules in ontoref-project.ncl.
secrets-bootstrap generates .sops.yaml from project.ncl in declarative mode. Three
new secrets-audit checks: recipient-routing-coherent, recipient-routing-coverage,
no-multi-vault. Adoption templates: single-team/, multi-tenant/, agent-first/.
Integration templates: domain-producer/, mode-producer/, mode-consumer/.
UI: project_picker surfaces registry badge (⟳ participant) and vault badge
(⛁ vault_id · N, green=declarative / amber=legacy) per project card. Expanded panel
adds collapsible Registry section with namespace, endpoint, and push/pull capability.
manage.html gains Runtime Services card — MCP and GraphQL toggleable without restart
via HTMX POST /ui/manage/services/{service}/toggle.
describe.nu: capabilities JSON includes registry_topology and vault_state per project.
sync.nu: drift check extended to detect //! absence on newly registered crates.
qa.ncl: six entries — credential-vault-best-practice (layered data-flow diagram),
credential-vault-templates (paths A/B/C), credential-vault-troubleshooting (15 named
errors), integration-what-and-why (ADR-042 OCI federation), integration-how-to-implement,
integration-troubleshooting.
on+re: core.ncl + manifest.ncl updated to reflect OCI, MCP, and mode-hierarchy nodes.
Deleted stale presentation assets (2026-02 slides + voice notes).
5.8 KiB
Ontoref — Scope: Proyecto, Infraestructura, Personal
Referencia para posts, slides, presentaciones. Contexto: ontoref como protocolo de auto-conocimiento para cualquier sistema con identidad e intención, más allá de gestión de proyectos de software.
La afirmación central
Ontoref no es una herramienta de gestión de proyectos. Es un protocolo de auto-conocimiento para cualquier sistema con identidad e intención.
Los tres dominios comparten la misma estructura profunda:
Ontology (Yin) Reflection (Yang)
────────────────────────── ──────────────────────────────
Proyecto Qué ES el software Qué DEVIENE — ADRs, modos,
principios, prácticas migraciones, deriva de docs
Infra Qué ES el sistema Qué DEVIENE — provisioning,
servicios, deps, drift detection, remediation,
constraints, topología runbooks como DAGs ejecutables
Personal Quién ERES Quién DEVIENS — decisiones con
valores, roles, consecuencias duraderas, hábitos,
principios vitales revisiones, deriva de intención
Infraestructura
Infra ya usa DAGs (Terraform, Pulumi, Ansible) pero todos inerts: describen cómo se provisiona, no por qué existe así. Ontoref sobre infra captura las tensiones reales:
Servicio "auth" --tension--> Principio "stateless"
porque necesita session state pero el principio dice no
Constraint "zero-downtime" --enforces--> Práctica "blue-green"
y eso está en el ADR-infra-003, no en el Terraform
jj + Radicle + NATS federation = GitOps soberano donde cada entorno (dev, staging, prod) se describe a sí mismo y puede ser consultado desde el proyecto que lo consume.
El problema que resuelve: infraestructura que deriva sin registro de por qué se tomaron las decisiones que la definen. El ADR de infra captura el "por qué" con el mismo peso que un ADR arquitectónico de software.
Personal
El dominio más radical. La misma pregunta que ontoref hace a un proyecto — ¿qué eres, qué tensiones activas tienes, en qué estado estás respecto a donde quieres estar? — es exactamente la pregunta que el conocimiento personal estructurado necesita responder.
No un segundo cerebro de notas. Un grafo de compromisos.
Valor "profundidad" --tension--> Rol "padre"
porque el tiempo es finito y los dos lo demandan
Decisión "dejar empresa X" --constraint--> Futuro laboral
con el mismo peso que un ADR arquitectónico
Estado "aprendiendo Rust" --blocker--> "contribuir a ontoref-core"
FSM personal, no lista de tareas
El problema que resuelve: la distancia entre quién intentas ser y quién estás siendo crece sin mecanismo de detección. Reflection personal es ese mecanismo.
Lo que todos los dominios comparten
Los tres tienen:
- Identidad — qué son, qué principios los definen
- Tensiones activas — trade-offs que no se resuelven, se gestionan
- Decisiones con consecuencias duraderas — el equivalente de ADRs
- Estado observable — dónde están vs. dónde quieren estar
- Deriva — la distancia entre intención y realidad que crece con el tiempo
- Operaciones — los modos que reducen esa deriva
Y todos se benefician del mismo stack:
- Almacenamiento soberano (NCL versionado junto al sujeto)
- Federación (NATS, modos federados)
- Multi-superficie (CLI + UI + MCP + GraphQL)
- VCS soberano (jj + Radicle)
El stack completo — lo que añade cada capa
Almacenamiento soberano: El enterprise knowledge graph asume un triplestore central. Ontoref invierte eso: el conocimiento vive con el sujeto, en NCL versionado. Nadie puede quitarte tu ontología porque está en tu repo/entorno/diario.
Modos federados: Proyectos que se describen a sí mismos Y pueden ser descubiertos y consultados por otros proyectos — sin servidor central.
proyecto-A consulta: ¿qué proyectos implementan "auth-pattern-X"?
proyecto-B, proyecto-C responden desde sus propias ontologías
sin intermediario que lo sepa todo
CLI + UI + MCP + GraphQL:
| Superficie | Consumidor |
|---|---|
| CLI (Nushell) | Desarrollador en terminal, scripts, CI |
| UI (axum) | Managers, revisión visual, onboarding |
| MCP | Agentes AI |
| GraphQL | Herramientas externas, dashboards, queries ad-hoc |
GraphQL sobre el DAG ontológico reduce la barrera de consumo sin sacrificar estructura. SPARQL es el estándar semántico pero requiere expertise. GraphQL es lo que todo el mundo escribe.
jj + Radicle:
- jj: cada working copy es siempre un commit — alinea con ontoref, no hay "estado sucio"
- Radicle: P2P, local-first, sin GitHub — si el código es soberano, el conocimiento sobre ese código también
Comparativa de posicionamiento
| Enterprise KG (Talisman) | Ontoref |
|---|---|
| Triplestore central | NCL distribuido, por sujeto |
| Equipo dedicado de ontólogos | El sujeto se mantiene a sí mismo |
| Dominio: datos organizacionales | Dominio: proyecto + infra + personal |
| GitHub/GitLab | jj + Radicle (soberano, P2P) |
| SPARQL sobre HTTP | CLI + UI + MCP + GraphQL |
| Un grafo global | Federación de sujetos auto-descritos |
| Escala: organización | Escala: individuo → proyecto → ecosistema |
Para slides — una línea por dominio
- Proyecto: El código sabe compilar. Ontoref hace que sepa qué es y por qué.
- Infra: Terraform sabe provisionar. Ontoref hace que sepa por qué existe así.
- Personal: Tu agenda sabe qué haces. Ontoref hace que sepas quién eres y hacia dónde derivas.
Cierre: El sujeto más pequeño que puede adoptar ontoref es una persona. El más grande es un ecosistema de proyectos federados.