From e53474a236d9061c7f4ee2a6c1e9fd0b5fe2651d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesu=CC=81s=20Pe=CC=81rez?= Date: Sun, 19 Jul 2026 18:36:16 +0100 Subject: [PATCH] docs(positioning): add "el-sujeto-no-se-alquila" narrative (es/en) --- site/site/content/adr/en/accepted/adr-012.md | 4 +- site/site/content/adr/en/accepted/adr-017.md | 2 +- site/site/content/adr/en/accepted/adr-018.md | 2 +- site/site/content/adr/en/accepted/adr-036.md | 2 +- site/site/content/adr/en/accepted/adr-037.md | 6 +- site/site/content/adr/en/accepted/adr-038.md | 2 +- site/site/content/adr/en/accepted/adr-039.md | 30 ++-- site/site/content/adr/en/accepted/adr-040.md | 12 +- site/site/content/adr/en/accepted/adr-043.md | 4 +- site/site/content/adr/en/accepted/adr-045.md | 2 +- site/site/content/adr/en/accepted/adr-067.md | 8 +- site/site/content/adr/en/accepted/adr-072.md | 2 +- site/site/content/adr/en/accepted/adr-074.md | 101 +++++++++++ site/site/content/adr/en/accepted/adr-074.ncl | 12 ++ site/site/content/blog/en/_index.ncl | 2 +- .../content/blog/en/engineering/_index.ncl | 2 +- site/site/content/blog/en/ontoref/_index.ncl | 3 +- .../en/ontoref/a-harness-without-a-subject.md | 165 ++++++++++++++++++ .../ontoref/a-harness-without-a-subject.ncl | 23 +++ site/site/content/blog/es/_index.ncl | 2 +- .../content/blog/es/engineering/_index.ncl | 2 +- site/site/content/blog/es/ontoref/_index.ncl | 3 +- .../es/ontoref/a-harness-without-a-subject.md | 163 +++++++++++++++++ .../ontoref/a-harness-without-a-subject.ncl | 23 +++ .../public/images/ontoref-architecture.svg | 8 +- 25 files changed, 537 insertions(+), 48 deletions(-) create mode 100644 site/site/content/adr/en/accepted/adr-074.md create mode 100644 site/site/content/adr/en/accepted/adr-074.ncl create mode 100644 site/site/content/blog/en/ontoref/a-harness-without-a-subject.md create mode 100644 site/site/content/blog/en/ontoref/a-harness-without-a-subject.ncl create mode 100644 site/site/content/blog/es/ontoref/a-harness-without-a-subject.md create mode 100644 site/site/content/blog/es/ontoref/a-harness-without-a-subject.ncl diff --git a/site/site/content/adr/en/accepted/adr-012.md b/site/site/content/adr/en/accepted/adr-012.md index 16d2612..07b4a46 100644 --- a/site/site/content/adr/en/accepted/adr-012.md +++ b/site/site/content/adr/en/accepted/adr-012.md @@ -14,7 +14,7 @@ css_class: "category-adr" ---

Context

-

Consumer projects have project-type-specific CLI needs that ontoref's generic command set cannot satisfy. A PersonalOntology project has CFP pipelines, career schemas, and opportunity tracking that no other repo_kind needs. A DevWorkspace project has workspace cards, cluster state dimensions, and production-readiness gates. These capabilities lived as local scripts (scripts/jpl.nu) — invisible to ontoref's help system, absent from describe capabilities, and not portable to other PersonalOntology projects. The problem had two layers: (1) how to conditionally load domain-specific Nu commands without breaking the existing dispatcher, and (2) how to make domain commands discoverable (help, describe capabilities) and aliasable (ore prov, personal state). Nu's module system (`use`, `source`, `overlay use`) is compile-time: paths must be known at parse time and `overlay use` creates an isolated namespace that cannot extend `def main` in the existing dispatcher. Runtime loading of arbitrary Nu modules is architecturally impossible in the current Nu model.

+

Consumer projects have project-type-specific CLI needs that ontoref's generic command set cannot satisfy. A PersonalOntology project has CFP pipelines, career schemas, and opportunity tracking that no other repo_kind needs. A DevWorkspace project has workspace cards, cluster state dimensions, and production-readiness gates. These capabilities lived as local scripts (scripts/jpl.nu) — invisible to ontoref's help system, absent from describe capabilities, and not portable to other PersonalOntology projects. The problem had two layers: (1) how to conditionally load domain-specific Nu commands without breaking the existing dispatcher, and (2) how to make domain commands discoverable (help, describe capabilities) and aliasable (ontoref prov, personal state). Nu's module system (`use`, `source`, `overlay use`) is compile-time: paths must be known at parse time and `overlay use` creates an isolated namespace that cannot extend `def main` in the existing dispatcher. Runtime loading of arbitrary Nu modules is architecturally impossible in the current Nu model.

Decision

@@ -26,7 +26,7 @@ css_class: "category-adr"

Alternatives considered

- +

Related ADRs

diff --git a/site/site/content/adr/en/accepted/adr-017.md b/site/site/content/adr/en/accepted/adr-017.md index 615db1e..3b45fa8 100644 --- a/site/site/content/adr/en/accepted/adr-017.md +++ b/site/site/content/adr/en/accepted/adr-017.md @@ -22,7 +22,7 @@ css_class: "category-adr"

Constraints

- +

Alternatives considered

diff --git a/site/site/content/adr/en/accepted/adr-018.md b/site/site/content/adr/en/accepted/adr-018.md index 0dbedd8..55c5f38 100644 --- a/site/site/content/adr/en/accepted/adr-018.md +++ b/site/site/content/adr/en/accepted/adr-018.md @@ -18,7 +18,7 @@ css_class: "category-adr"

Decision

-

Formalize the three-level hierarchy with four mechanisms: (1) Level identity declaration — each ontoref instance declares level.index (1=base, 2=domain, 3=instance), level.name, and level.parent (name of the level above; absent at level 1) in manifest.ncl. This makes level identity explicit and queryable. (2) Per-mode resolution strategy — each reflection mode declares a strategy field using one of four values: 'Override (implementation is complete at this level, traversal stops), 'Delegate (no implementation here, traverse to parent), 'Merge (accumulate fields bottom-up across all levels; lower level wins on conflicts), 'Compose (declare explicit partial inheritance via an extends field naming specific steps or fields to inherit from the parent). Strategy is required at level 2+; absent at level 1 (base is always Override by definition). Implicit absence at level 2+ is treated as 'Delegate with a Soft validation warning. (3) FSM-bound strategy transitions — when a mode's strategy is expected to change as the project matures, declare a state dimension in state.ncl whose current_state tracks the strategy value. The transition from 'Delegate to 'Override (or any other pair) is then an observable FSM event: tracked in state.ncl, visible in ore describe state, and triggerable by the same transition conditions as any other dimension. Strategy changes are architectural events, not silent refactors. (4) Observable traversal via ore mode resolve — the command 'ore mode resolve <id>' reports which level answered the operation, the strategy applied, the source file, and the reason (declared strategy or FSM state). No mode resolution is ever silent.

+

Formalize the three-level hierarchy with four mechanisms: (1) Level identity declaration — each ontoref instance declares level.index (1=base, 2=domain, 3=instance), level.name, and level.parent (name of the level above; absent at level 1) in manifest.ncl. This makes level identity explicit and queryable. (2) Per-mode resolution strategy — each reflection mode declares a strategy field using one of four values: 'Override (implementation is complete at this level, traversal stops), 'Delegate (no implementation here, traverse to parent), 'Merge (accumulate fields bottom-up across all levels; lower level wins on conflicts), 'Compose (declare explicit partial inheritance via an extends field naming specific steps or fields to inherit from the parent). Strategy is required at level 2+; absent at level 1 (base is always Override by definition). Implicit absence at level 2+ is treated as 'Delegate with a Soft validation warning. (3) FSM-bound strategy transitions — when a mode's strategy is expected to change as the project matures, declare a state dimension in state.ncl whose current_state tracks the strategy value. The transition from 'Delegate to 'Override (or any other pair) is then an observable FSM event: tracked in state.ncl, visible in ontoref describe state, and triggerable by the same transition conditions as any other dimension. Strategy changes are architectural events, not silent refactors. (4) Observable traversal via ontoref mode resolve — the command 'ontoref mode resolve <id>' reports which level answered the operation, the strategy applied, the source file, and the reason (declared strategy or FSM state). No mode resolution is ever silent.

Constraints

diff --git a/site/site/content/adr/en/accepted/adr-036.md b/site/site/content/adr/en/accepted/adr-036.md index 00cd50e..c94e33e 100644 --- a/site/site/content/adr/en/accepted/adr-036.md +++ b/site/site/content/adr/en/accepted/adr-036.md @@ -77,7 +77,7 @@ implementation is tracked as backlog item bl-014.

Alternatives considered

- +

Related ADRs

diff --git a/site/site/content/adr/en/accepted/adr-037.md b/site/site/content/adr/en/accepted/adr-037.md index 62ed14c..c7093cf 100644 --- a/site/site/content/adr/en/accepted/adr-037.md +++ b/site/site/content/adr/en/accepted/adr-037.md @@ -77,14 +77,14 @@ reflection schema `reflection/schemas/interaction.ncl` (migration 0028).

rather than redeclaring parallel vocabularies that would drift. The runtime validator parses enum members FROM the schema files at runtime, so the allowlist can never diverge from the contract.

-

5. Two emission paths, both supported. `ore interaction record` validates a +

5. Two emission paths, both supported. `ontoref interaction record` validates a record structurally before appending (the forced path; malformed records are rejected). Direct JSONL append by the agent is also permitted (the - free path), audited post-hoc by `ore interaction validate` (pre-commit / + free path), audited post-hoc by `ontoref interaction validate` (pre-commit / CI gate). The `--no-validate` flag bridges the two on the same command.

6. Decisions materialise the adr? criteria as data. `Decision` carries `alternatives_rejected`, `reversible`, `adr_candidate`, and - `tensions_engaged` (core.ncl node ids). `ore interaction decisions + `tensions_engaged` (core.ncl node ids). `ontoref interaction decisions --adr-candidates` surfaces ADR candidates across sessions in one query, feeding the ADR lifecycle from observed decisions rather than recollection.

The layer is opt-in per ADR-029: a project that never emits interaction JSONL diff --git a/site/site/content/adr/en/accepted/adr-038.md b/site/site/content/adr/en/accepted/adr-038.md index 94bf048..583638b 100644 --- a/site/site/content/adr/en/accepted/adr-038.md +++ b/site/site/content/adr/en/accepted/adr-038.md @@ -55,7 +55,7 @@ schema/catalog additions to consumers.

build kind, the build/distribution catalog entries, and the generator that emits .woodpecker/release.yml + install/install.sh + justfiles/release.just all live in the NCL workflow model. Distribution is therefore self-describing - and queryable via `ore workflow`, like every other build/CI artifact.

+ and queryable via `ontoref workflow`, like every other build/CI artifact.

2. Build-once; the image is assembled FROM the binary, never recompiled. The musl binary is cross-compiled once per arch (`cross`). Both the install bundle AND the runnable image consume that same binary. The image is diff --git a/site/site/content/adr/en/accepted/adr-039.md b/site/site/content/adr/en/accepted/adr-039.md index 2c11b18..3c10564 100644 --- a/site/site/content/adr/en/accepted/adr-039.md +++ b/site/site/content/adr/en/accepted/adr-039.md @@ -17,7 +17,7 @@ css_class: "category-adr"

Projects accumulate many just recipes (and loose scripts). ontoref already INVENTORIES recipes — describe.nu::scan-just-recipes runs `just --list` and categorizes each recipe by a name-prefix heuristic (categorize-recipe), and -`ore describe tools` lists them. But the inventory is shallow: it knows a +`ontoref describe tools` lists them. But the inventory is shallow: it knows a recipe's name, its trailing `#` comment, and a guessed bucket. It cannot answer "which is the canonical way to run all checks", "show me the deploy tasks", or "what does build-standalone do and why" — because the recipe carries no declared @@ -26,16 +26,16 @@ INTENT and no real categorization, only a prefix guess.

- Recipes (justfiles) are the MECHANISM layer — the concrete command. Single source of truth for HOW. - Modes (reflection/modes/*.ncl) are the PROCEDURE layer — multi-step gated - DAGs with actors/steps/depends_on, executed by `ore run`.

+ DAGs with actors/steps/depends_on, executed by `ontoref run`.

What is missing is not a third store ("devtask" is a target-side abstraction, not ontoref vocabulary). What is missing is for a recipe to SELF-DESCRIBE — to declare its intent and categorization in place — exactly as Rust handlers do with #[onto_api(method, path, description, tags)]: the annotation sits next to the code, a proc-macro parses it, and inventory aggregates a zero-cost catalog -that `ore describe api` / GET /api/catalog / MCP all read. The same shape is +that `ontoref describe api` / GET /api/catalog / MCP all read. The same shape is wanted for recipes: an annotation next to the recipe, parsed by ontoref, that makes justfiles queryable.

-

The qa routing fix in the same session (ore qa show/list/search/add) added the +

The qa routing fix in the same session (ontoref qa show/list/search/add) added the seeding primitive — a tag-categorized, nickel-validated write path. The question this ADR settles is the GRAMMAR and the BOUNDARIES of seeding/enriching the tool surface: how an annotation is written, how it is mutated, and how a project that @@ -67,14 +67,14 @@ grammar, the recommended mode taxonomy, and the new surface to consumers.

2. The recipe is the single source of truth. Annotations live IN the justfile, above the recipe — never in a parallel devtasks store. ontoref parses them (scan-just-recipes gains an @onto parser) and DERIVES a catalog, exactly as - #[onto_api] derives artifacts/api-catalog-*.ncl. `ore tool export` writes the - derived catalog; `ore describe tools --mode <m> --label <l>` reads it.

-

3. Mutation via a transversal verb. `ore + <noun> <args>` upserts and - `ore - <noun> <args>` removes, across stores:

-

ore + tool ci-full --mode ci --labels ci,gate --intent "all checks" - ore - tool ci-full # removes the @onto line only - ore + qa "<q>" "<a>" --tags devtool,ci # the qa add path - ore - qa <id>

+ #[onto_api] derives artifacts/api-catalog-*.ncl. `ontoref tool export` writes the + derived catalog; `ontoref describe tools --mode <m> --label <l>` reads it.

+

3. Mutation via a transversal verb. `ontoref + <noun> <args>` upserts and + `ontoref - <noun> <args>` removes, across stores:

+

ontoref + tool ci-full --mode ci --labels ci,gate --intent "all checks" + ontoref - tool ci-full # removes the @onto line only + ontoref + qa "<q>" "<a>" --tags devtool,ci # the qa add path + ontoref - qa <id>

`+ tool` / `- tool` edit the `@onto` comment ABOVE the named recipe in place, validated against `just --list`; they NEVER touch the recipe body. `+`/`-` are first-level dispatcher tokens taking `<noun> <args>`, so new @@ -84,7 +84,7 @@ grammar, the recommended mode taxonomy, and the new surface to consumers.

behavior). Annotation raises a recipe from guessed to declared; it is never required to run a recipe. This is the `formalization-vs-adoption` balance made literal — "optional layers, not mandatory gates".

-

5. Non-destructive compliance/migration. A `compliant` mode (and `ore tool +

5. Non-destructive compliance/migration. A `compliant` mode (and `ontoref tool migrate`) scans a project's existing justfiles, proposes `@onto` annotations (seeding `mode` from categorize-recipe + name, leaving `intent` for the author), and — opt-in — reorganizes recipes into justfiles/<mode>.just. It @@ -92,7 +92,7 @@ grammar, the recommended mode taxonomy, and the new surface to consumers.

deleted or renamed, reorg is opt-in and reversible, and the project's own recipes are first-class (the mechanism annotates them, it does not supplant them with ontoref-blessed ones).

-

6. Drift-checkable round-trip. `ore tool audit` reports orphan annotations +

6. Drift-checkable round-trip. `ontoref tool audit` reports orphan annotations (an `@onto` whose recipe is gone from `just --list`) and, at compliance level, un-annotated recipes. Mirrors docs-drift: the annotation and the recipe must stay in sync because they are co-located.

@@ -102,7 +102,7 @@ annotated recipes are complementary, not competing.

Constraints

- +

Alternatives considered

diff --git a/site/site/content/adr/en/accepted/adr-040.md b/site/site/content/adr/en/accepted/adr-040.md index ff2c317..a1f8dcb 100644 --- a/site/site/content/adr/en/accepted/adr-040.md +++ b/site/site/content/adr/en/accepted/adr-040.md @@ -100,7 +100,7 @@ truth.

with its own in one directory. The DECLARATION (card.ncl) plus the .ontoref/ content are the source of truth; the .claude/ symlink is a derived view.

5. Propagation rides the update/migration mechanism, not bespoke symlink edits. - `ore conventions sync` (and the `update_ontoref` mode) reconcile each declared + `ontoref conventions sync` (and the `update_ontoref` mode) reconcile each declared binding against the shared origin: detect version drift (origin moved, e.g. new Rust guideline), report it, and — opt-in — re-link or re-vendor to the declared version. A shared change reaches every binding project through this @@ -114,26 +114,26 @@ truth.

means writing it to the origin and re-syncing, so all binding projects can adopt it.

7. Optional, audit-not-gate. A project may declare zero conventions and remain - valid. `ore conventions audit` reports: bindings whose origin is unreachable, + valid. `ontoref conventions audit` reports: bindings whose origin is unreachable, version drift (declared != origin), and resolution-mode mismatches (declared symlink but found vendored, or vice versa). It REPORTS; it does not block — the formalization-vs-adoption resolution.

These are MODES/utilities, not new stores: per the user's framing, guidelines/CI/ config bindings are implementation-framework utilities (templates, examples, -sync). `ore conventions sync|audit|describe` and the `update_ontoref` extension +sync). `ontoref conventions sync|audit|describe` and the `update_ontoref` extension are the operational surface; card.ncl carries the declaration.

Constraints

- +

Alternatives considered

- +

Anti-patterns

- +

Related ADRs

diff --git a/site/site/content/adr/en/accepted/adr-043.md b/site/site/content/adr/en/accepted/adr-043.md index 62ab0f0..06e5d5d 100644 --- a/site/site/content/adr/en/accepted/adr-043.md +++ b/site/site/content/adr/en/accepted/adr-043.md @@ -54,7 +54,7 @@ first-class typed kind, bound by a Proof seam:

The crossings are explicit: `ValueProp` is the WHAT×WHOM seam (gains `differentiator_ids`); `Campaign` and `Proof` bind HOW and VALIDATION.

The marketing surface is governed by the same mechanism it sells. Five coherence -rules run in `ore positioning audit` (local-first, daemon-independent):

+rules run in `ontoref positioning audit` (local-first, daemon-independent):

1. AnchorDrift — a differentiator/proof evidence_adr must be Accepted. 2. UnprovenValidatedAudience — an Audience marked 'Validated needs >=1 Proof. 3. Live value-prop — must converge four elements (differentiator + @@ -69,7 +69,7 @@ Validated/Live claims must cite Accepted ADRs — mirroring the

Constraints

- +

Alternatives considered

diff --git a/site/site/content/adr/en/accepted/adr-045.md b/site/site/content/adr/en/accepted/adr-045.md index daf3d15..093799b 100644 --- a/site/site/content/adr/en/accepted/adr-045.md +++ b/site/site/content/adr/en/accepted/adr-045.md @@ -18,7 +18,7 @@ css_class: "category-adr"

Decision

-

Generalize ADR-018's absolute triad into a relative parent chain and add a co-tenancy declaration, both opt-in and backward-compatible, via four mechanisms. (1) RELATIVE LEVEL CHAIN — level identity is the parent chain, not an absolute index. A manifest declares level.parent (a name reference, exactly as ADR-018) and an optional level.role label; level.index becomes a DERIVED depth (walk parents to a base) that is no longer capped at 3 and no longer authoritative. The names base/domain/instance are reinterpreted as ROLES in a sliding window of three relative to an observation point, not global coordinates. Existing index 1/2/3 declarations remain valid as the depth<=3 case; deeper chains simply keep walking. The terminal node of one chain may itself be the parent-root of another (instance-as-host is a well-formed shape, not an error). (2) DOMAIN CO-TENANCY — a repo may declare manifest.ncl::hosts, an array of { chain (name reference to a foreign domain artifact), mount (where in this repo the hosted chain's Layer-3 wiring lives), digest (optional witness pin) }. The foreign chain is resolved by name through catalog discovery (ADR-030) and verified by witness (ADR-028), NEVER cloned. The host carries only Layer-3 wiring for the hosted chain (ADR-020), tagged layer-3-boundary. (3) MUTATION SOVEREIGNTY UNDER CO-TENANCY — a host's runtime MUST NOT mutate the authoritative state of any hosted chain. Hosting is placement plus wiring; each chain's authoritative state mutates only through its own declared operations with its own witness (ADR-024). Co-tenancy is co-residency of wiring, not transfer of state ownership. (4) OBSERVABLE CROSS-CHAIN RESOLUTION — ore mode resolve extends to report the full traversal PATH (every level visited, not a single hop) and the CHAIN SCOPE (which chain answered) when multiple chains are co-resident; ore describe state disambiguates FSM dimensions by chain scope. No cross-chain resolution is silent.

+

Generalize ADR-018's absolute triad into a relative parent chain and add a co-tenancy declaration, both opt-in and backward-compatible, via four mechanisms. (1) RELATIVE LEVEL CHAIN — level identity is the parent chain, not an absolute index. A manifest declares level.parent (a name reference, exactly as ADR-018) and an optional level.role label; level.index becomes a DERIVED depth (walk parents to a base) that is no longer capped at 3 and no longer authoritative. The names base/domain/instance are reinterpreted as ROLES in a sliding window of three relative to an observation point, not global coordinates. Existing index 1/2/3 declarations remain valid as the depth<=3 case; deeper chains simply keep walking. The terminal node of one chain may itself be the parent-root of another (instance-as-host is a well-formed shape, not an error). (2) DOMAIN CO-TENANCY — a repo may declare manifest.ncl::hosts, an array of { chain (name reference to a foreign domain artifact), mount (where in this repo the hosted chain's Layer-3 wiring lives), digest (optional witness pin) }. The foreign chain is resolved by name through catalog discovery (ADR-030) and verified by witness (ADR-028), NEVER cloned. The host carries only Layer-3 wiring for the hosted chain (ADR-020), tagged layer-3-boundary. (3) MUTATION SOVEREIGNTY UNDER CO-TENANCY — a host's runtime MUST NOT mutate the authoritative state of any hosted chain. Hosting is placement plus wiring; each chain's authoritative state mutates only through its own declared operations with its own witness (ADR-024). Co-tenancy is co-residency of wiring, not transfer of state ownership. (4) OBSERVABLE CROSS-CHAIN RESOLUTION — ontoref mode resolve extends to report the full traversal PATH (every level visited, not a single hop) and the CHAIN SCOPE (which chain answered) when multiple chains are co-resident; ontoref describe state disambiguates FSM dimensions by chain scope. No cross-chain resolution is silent.

Constraints

diff --git a/site/site/content/adr/en/accepted/adr-067.md b/site/site/content/adr/en/accepted/adr-067.md index b88fc2e..7d6ddf2 100644 --- a/site/site/content/adr/en/accepted/adr-067.md +++ b/site/site/content/adr/en/accepted/adr-067.md @@ -16,7 +16,7 @@ css_class: "category-adr"

ADR-035 established positioning as a queryable protocol surface and ADR-043 modelled it as four elements (WHAT / FOR WHOM / HOW bound by the Proof seam), -governed by the five coherence rules of `ore positioning audit` — the first of +governed by the five coherence rules of `ontoref positioning audit` — the first of which, AnchorDrift, requires that every `evidence_adr` cited by a Differentiator or Proof resolves to an Accepted ADR. Both ADRs were authored when the positioning surface had exactly one occupant: ontoref itself. In a single-project @@ -34,7 +34,7 @@ only in rustelo's ADR catalogue, not ontoref's.

Working the placement through surfaced the load-bearing fact: a rustelo Differentiator authored inside ontoref's `.ontoref/positioning/` would FAIL AnchorDrift, because ontoref does not own those ADRs. Authored inside rustelo's -own `.ontoref/positioning/`, the same subject passes — verified: `ore positioning +own `.ontoref/positioning/`, the same subject passes — verified: `ontoref positioning audit` run from rustelo reports `adr-drift: none`. The audit already resolves `evidence_adrs` against the AUTHORING project's ADR set; the framework simply never named where that places a subject. This is the same authority-upstream / @@ -68,7 +68,7 @@ the rustelo publishing-contract.

Constraints

- +

Alternatives considered

@@ -76,7 +76,7 @@ the rustelo publishing-contract.

Anti-patterns

- +

Related ADRs

diff --git a/site/site/content/adr/en/accepted/adr-072.md b/site/site/content/adr/en/accepted/adr-072.md index ad2d63a..b97becc 100644 --- a/site/site/content/adr/en/accepted/adr-072.md +++ b/site/site/content/adr/en/accepted/adr-072.md @@ -23,7 +23,7 @@ UNWITNESSED. So a check can go green over a shrinking fraction of reality and it perfectly valid. It does not fail. It does not warn. It looks where it always looked, finds nothing wrong there, and signs.

AND THE COVERAGE EXPIRES PRECISELY WHEN YOU IMPROVE THE MECHANISM. That is the finding, and it is -not a metaphor. In one session, on one witness (`ore rustelo routes`), THREE TIMES:

+not a metaphor. In one session, on one witness (`ontoref rustelo routes`), THREE TIMES:

· the SITE gained ownership of its templates (adr-070's overlay). The witness read only the framework's `crates/pages_htmx/templates/` and reported a site-owned page as broken. · the CONSUMER gained ownership of its routes (`merge_site_routes`). The witness read only the diff --git a/site/site/content/adr/en/accepted/adr-074.md b/site/site/content/adr/en/accepted/adr-074.md new file mode 100644 index 0000000..081aa87 --- /dev/null +++ b/site/site/content/adr/en/accepted/adr-074.md @@ -0,0 +1,101 @@ +--- +id: "adr-074" +title: "Context-provision is governed — ontoref is the single source of truth about the protocol; carriers invoke it live and hold no protocol content, pointers, or verifiers of their own" +slug: "074" +subtitle: "Accepted" +excerpt: "A session — a person or an agent — arrives needing to know how the protocol works: how a project" +author: "ontoref" +date: "2026-07-18" +published: true +featured: false +category: "accepted" +tags: ["adr-074", "adr", "accepted"] +css_class: "category-adr" +--- +

Context

+ +

A session — a person or an agent — arrives needing to know how the protocol works: how a project +self-governs its relation to a domain, what vocabulary is mandatory, how bonds are declared and +retyped. The convenient move, and the one this session nearly took, is to answer where the session +already looks: write the how-to into the project's CLAUDE.md, propagate a bond-vocabulary block into +every consumer's CLAUDE.md, plant a topic-specific line into a SessionStart hook under `~/.claude/`, +add a verifier next to it. Four turns of the same reflex: put the truth where the reader is standing.

+

That reflex is drift by construction, and the ontology already names why. `dev-internal-overlay` +classes `.claude/` as dev-internal OPERATIONAL CONFIG — a carrier, not a home for governed content. +`ontoref-three-layer-model` states the rule generically: protocol truth is Layer 1 / protocol-qa, +and "this entry exists so adopters discover the layering from protocol documentation, not by +re-deriving it across three projects"; Layer 3 (per-caller, per-machine wiring) is OUTPUT of a +relationship, "never in this project's repo", referenced by "explicit pointers, never copy-paste". +ADR-028 already forbids the clone: the ontology is addressable independently and a consumer verifies +BY WITNESS, NOT BY COPY.

+

The sharp form of the requirement, as stated in-session: we do not want channels, pointers, +declarations, or verifiers SCATTERED across the universe and its constellations on one particular +machine's disk. ontoref is the one that governs, and is responsible for the truth about questions +like these AS SUCH. The failure is not that carriers exist — an agent does read CLAUDE.md first, and +that is legitimate reach. The failure is content, pointers, and verifiers ACCRETING in those carriers +as a second authority that no witness keeps in sync with the governed surface. Two copies, no witness, +guaranteed divergence the first time one is edited and the other is not.

+

There is already a correct shape in production and it was almost overlooked: the generic on+re +conduits (the SessionStart orient hook, the UserPromptSubmit routing that answers "esto ya está +gobernado — `ontoref qa show <id>`"). They carry NO protocol content. They ASK ontoref, at read-time, +which governed entry houses the current topic, and surface a live pointer INTO the governed surface. +The content stays in ontoref; the routing is decided by ontoref; the carrier is a thin, generic, +topic-agnostic conduit. That is the pattern this ADR ratifies and generalizes — and it is the pattern +whose alternative (topic-specific truth accreting per carrier, per machine) it forbids.

+ +

Decision

+ +

CONTEXT-PROVISION ABOUT THE PROTOCOL IS GOVERNED. ontoref's own surface — the ontology, reflection +(qa, modes, disciplines, substrate views), adrs, the CLI/daemon/MCP that serve them — is the SINGLE +SOURCE OF TRUTH and the SINGLE RESPONSIBLE AUTHORITY for how the protocol works. The answer to a +"how does X work in the protocol" question is a QUERY answered by ontoref, reached by asking ontoref +at one addressable locus, not a copy read from wherever the asker happened to be standing.

+

Three rules follow, and they are the contract:

+

1. TRUTH LIVES ONLY IN THE GOVERNED SURFACE. Protocol knowledge is authored once, in ontology or + reflection, where ontoref can type it, validate it, witness it and version it. A qa entry, a + discipline, a schema, an ADR — these are homes. A carrier is not.

+

2. CARRIERS INVOKE; THEY DO NOT REPLICATE. An external carrier (a project or global CLAUDE.md, + MEMORY.md, a SessionStart/UserPromptSubmit hook, an agent memory index) may hold at most a THIN, + GENERIC, TOPIC-AGNOSTIC invocation that resolves against ontoref at read-time — the shape the + orient/routing hooks already have. It holds NO protocol content, NO topic-specific pointer table, + NO per-topic declaration. Routing is ontoref's job (the hook asks ontoref which entry is + relevant), never a hand-maintained map in the carrier.

+

3. THE GOVERNOR VERIFIES; VERIFIERS ARE NOT SCATTERED. If a check is needed that a carrier has not + accreted duplicated truth, that check is ONE command inside ontoref auditing its own carriers — + the governor doing its job — never a validator planted per-machine, per-repo, next to each + carrier as its own little authority. Centralized-in-ontoref is the cure; scattered-across-disk + is the disease, and a scattered verifier is the disease wearing the cure's clothes.

+

Corollary for the bond work that surfaced this (adr-073): the bond how-to lives as ONE governed qa +entry (`bond-carrier-layout-howto` in `reflection/qa.ncl`) and as the `bonding` discipline/substrate +view that references it — NOT as a bond section propagated into consumer CLAUDE.md files, NOT as a +bond-specific hook line, NOT as a per-repo bond verifier. The existing bond vocabulary block in the +producer-level CLAUDE.md is legacy duplication under this ADR and is to be thinned to the generic +"ask ontoref" conduit, not extended.

+

SCOPE — TRUTH, NOT INSTRUMENTS. This ADR governs protocol TRUTH: definitions, directives, +vocabulary, how-the-protocol-works knowledge. OPERATIONAL INSTRUMENTS — fill-in-the-blanks forms, +materializable templates, prompt scaffolds, mode step-sequences (reflection/forms/, +reflection/templates/, reflection/modes/) — are NOT carriers of truth: filling one produces a +disposable work product, not a second authority, and materializing one is not replication. An +instrument crosses into this ADR's territory only when it INLINES governed content instead of +referencing it. That boundary is watched SOFTLY, from one place — the instrument registry +(reflection/instruments.ncl) read by `sync instruments check` — and softly on purpose: an +instrument may legitimately NUANCE or EXPLAIN governed content with no intent to stand over the +governance; a match is a finding for a human to judge, never an automatic verdict of drift.

+

This ADR is itself an instance of its own rule: it is authored once, here, in the governed adrs/ +surface; every carrier that needs it points a session at `ontoref` to read it, and copies nothing.

+ +

Constraints

+ + + +

Alternatives considered

+ + + +

Anti-patterns

+ + + +

Related ADRs

+ +

ADR-073 · ADR-028 · ADR-046 · ADR-062 · ADR-018

diff --git a/site/site/content/adr/en/accepted/adr-074.ncl b/site/site/content/adr/en/accepted/adr-074.ncl new file mode 100644 index 0000000..2752a69 --- /dev/null +++ b/site/site/content/adr/en/accepted/adr-074.ncl @@ -0,0 +1,12 @@ +{ + id = "adr-074", + title = "Context-provision is governed — ontoref is the single source of truth about the protocol; carriers invoke it live and hold no protocol content, pointers, or verifiers of their own", + slug = "074", + excerpt = "", + tags = ["adr", "accepted"], + page_route = "/adr/074", + graph = { + implements = [], + related_to = ["adr-073", "adr-028", "adr-046", "adr-062", "adr-018"], + }, +} diff --git a/site/site/content/blog/en/_index.ncl b/site/site/content/blog/en/_index.ncl index a25fcea..ed92f22 100644 --- a/site/site/content/blog/en/_index.ncl +++ b/site/site/content/blog/en/_index.ncl @@ -1,6 +1,6 @@ # AUTO-GENERATED — do not edit manually # Scope: blog/en -# Updated: 2026-07-17T05:56:25Z +# Updated: 2026-07-19T04:50:00Z # Regen: nu scripts/content/generate-ncl-index.nu std.array.flatten [ diff --git a/site/site/content/blog/en/engineering/_index.ncl b/site/site/content/blog/en/engineering/_index.ncl index 03dc6a2..fc14bfb 100644 --- a/site/site/content/blog/en/engineering/_index.ncl +++ b/site/site/content/blog/en/engineering/_index.ncl @@ -1,6 +1,6 @@ # AUTO-GENERATED — do not edit manually # Scope: blog/en/engineering -# Updated: 2026-07-17T05:56:25Z +# Updated: 2026-07-19T04:50:00Z # Regen: nu scripts/content/generate-ncl-index.nu [ diff --git a/site/site/content/blog/en/ontoref/_index.ncl b/site/site/content/blog/en/ontoref/_index.ncl index f4e3e0f..3be416b 100644 --- a/site/site/content/blog/en/ontoref/_index.ncl +++ b/site/site/content/blog/en/ontoref/_index.ncl @@ -1,9 +1,10 @@ # AUTO-GENERATED — do not edit manually # Scope: blog/en/ontoref -# Updated: 2026-07-17T05:56:25Z +# Updated: 2026-07-19T04:50:00Z # Regen: nu scripts/content/generate-ncl-index.nu [ + import "./a-harness-without-a-subject.ncl", import "./a-rule-without-a-trigger-is-a-sign.ncl", import "./ai-knowledge-tool-who-keeps-it-alive.ncl", import "./context-declared-not-filled.ncl", diff --git a/site/site/content/blog/en/ontoref/a-harness-without-a-subject.md b/site/site/content/blog/en/ontoref/a-harness-without-a-subject.md new file mode 100644 index 0000000..3bd5fef --- /dev/null +++ b/site/site/content/blog/en/ontoref/a-harness-without-a-subject.md @@ -0,0 +1,165 @@ +--- +# Post metadata +id: "a-harness-without-a-subject" +title: "A harness without a subject: what harness engineering doesn't name yet" +slug: "a-harness-without-a-subject" +subtitle: "The AI harness is the word of the year: the five layers that wrap a model so it can do real work. But a minimal harness is a hundred lines, every vendor now ships one, and the advantage is moving one layer down — to the subject the harness consults." +excerpt: "Harness engineering just named itself as a discipline: documentation as code, architectural constraints, layered verification, periodic consistency audits. All four pillars exist — in flat markdown, held up by manual discipline. This post concedes the whole argument (“the model is commodity, the harness is the advantage”) and adds the next step: the harness governs the verb — how a change is made — and names no subject to check it against. A verb without a subject cannot drift, because drift is precisely a subject diverging from its own declared self." + +# Publication info +author: "Jesús Pérez" +date: "2026-07-19" +published: true +featured: true + +# Categorization +category: "ontoref" +tags: ["ontoref", "harness", "harness-engineering", "agents", "drift", "developer"] + +# Display +sort_order: 9 + +# Image (card thumbnail + in-post featured) +thumbnail: "/images/ontoref-harness-without-a-subject.webp" +image_url: "/images/ontoref-harness-without-a-subject.webp" +og_image: "/images/og/ontoref-harness-without-a-subject.png" +--- + + + + + A harness without a subject: what harness engineering doesn't name yet + + +There is a term going around — the *AI harness* — doing for 2026 what *prompt +engineering* did for 2022 and *context engineering* for 2025: naming the place +where the outcome is actually decided. The definition settling in +([webreactiva's summary](https://www.webreactiva.com/blog/ai-harness) is a good +one) is clean: the harness is **everything that wraps the model so it can do +real work** — tools, system prompt, context management, permissions, and +verification loops. The model is the engine; the harness is the whole vehicle. +And the numbers behind the thesis are serious: the same model going from 52.8% +to 66.5% on a benchmark with only the harness changed; another jumping from +6.7% to 68.3% by changing nothing but the edit format; LangChain measuring +10–20 point jumps on tau2-bench just by adding model-specific harness profiles +([DataCamp's survey](https://www.datacamp.com/blog/agent-harness) collects +them and states the now-canonical equation: **agent = model + harness**). +Hence the slogan: *the model is commodity, the harness is the competitive +advantage*. + +Conceded. All of it. The harness matters more than the model, and anyone who +has run a real agent doesn't need to be told twice. + +Now the step the slogan doesn't take. + +## The harness is becoming commodity too + +The argument carries this inside itself: a minimal harness — read file, list +files, edit file — fits in **under a hundred lines**. Every vendor now ships +one, and the open-source ones come by the dozen. When the piece that was the +advantage can be reproduced in an afternoon, the advantage doesn't vanish: **it +moves one layer down**. The question stops being "which harness runs your +agent?" and becomes "what does your harness find when it asks *what is this +project, and what has it decided?*" + +For most teams, the honest answer is: a pile of markdown. And that is not a +caricature — it is the component's own definition: when the harness literature +enumerates its "memory and state", what it lists is files, logs, and +summaries. State without a type, prose without a contract. + +## Four verbs, no subject + +Look at the full vocabulary of the agent era: you **orchestrate** workflows, +wrap them in **guardrails**, run them inside a **harness**, **harvest** their +output back into memory. Four verbs, one grammar — and all four govern the +**act**. Not one names a **subject**: a thing the project has declared itself +to be, that could be checked for still being true. + +That omission is not a gap in the vocabulary; it is its function. A verb +without a subject **cannot drift**, because drift is precisely that: a subject +diverging from its own declared self over time. What you cannot name, you +cannot measure. That is why the ecosystem can ship ever-better harnesses and +still have no answer to the one question that matters at agent speed: *is what +you declared six weeks ago still true?* The question is not expressible in the +grammar it chose. + +The harness is a **spatial** instrument: it contains the act in the moment it +happens — this context, these permissions, this verification, now. Drift is +**temporal**: the slow separation between what a system says it is and what it +has become, measured in commits and sessions, not in tokens. You cannot build +a fence against time. + +## The four pillars, typed + +What makes *harness engineering* interesting as a named discipline — Mitchell +Hashimoto named it in February 2026 — is that its four pillars map the problem +exactly. It's just that each pillar is practiced today in its informal form: +flat markdown held up by manual discipline. Each has a typed form, and the +difference between the two is whether coherence is **hoped for** or +**checked**: + +| Harness engineering pillar | Informal form | Typed form in ontoref | +|---|---|---| +| Documentation as code | `AGENTS.md` — prose the agent reads | An ontology queryable as data: `describe` answers *what is this, what can I do, what is the impact of touching X* | +| Architectural constraints | Conventions stated in text | Hard/Soft constraints on every ADR, evaluated by `validate-adrs`: a violation **fails CI** | +| Layered verification | Hooks and human review | Structural gates + a signed witness: every act that mutates the model emits a witness; every mutation is the deposit of a witnessed act | +| Garbage collection | Periodic consistency audits | Drift as a first-class value: an observer compares declaration against artifact and **proposes** the fix — never applies it silently | + +The fourth row is the most revealing. "Collecting garbage" every so often is +admitting the system drifts and resigning yourself to sweeping up. Treating +drift as an observable value — something a process detects, names, and turns +into a reviewable mutation proposal — is refusing to let the gap between map +and territory stay invisible while it grows. + +## Your harness doesn't compete with this — it consults it + +Here is the division of roles, stated without ambiguity: **ontoref is not a +harness and does not pretend to be one**. It doesn't own the tool loop, it +executes nothing on the model's behalf, it will not orchestrate your agents +better. It is the layer the harness finds when it asks: the **subject** — a +typed model of the project: its decisions with their constraints, its state +with its transition conditions, its tensions held rather than collapsed — that +any harness can query as data and check every change against. + +The recent taxonomy distinguishes three layers — framework (LangChain, +CrewAI), runtime (LangGraph, Temporal), and harness (Deep Agents, the agent +SDKs) — and ontoref sits in none of the three: it is what all three consult. +There is also a hard reason it must live outside, and the literature itself +supplies it when it admits its open tension: results become **tightly coupled +to the specific harness profile**, and switching harness or model is costly. +If the project's knowledge lives inside that profile, changing vehicles means +losing it — you are hostage to your harness. A subject declared outside any +harness is portable across all of them: accountable to its model, hostage to +none. + +The relation is invocation, not replication: the harness (Claude Code, or any +other) carries a live pointer to the governed surface; it never copies the +content, because a copy is the first drift. And the protocol eats its own +cooking: ontoref describes itself with its own protocol — its ontology, its +ADRs, and its reflection layer are ontoref consuming ontoref. The subject it +asks you to declare is the one it maintains for itself, and it fails its own CI +when that stops being true. + +## The honest boundary + +Keep your harness. Improve it: the five layers are real and so are the +numbers. But when the freshly named discipline tells you the advantage lives +in the environment rather than the model, ask it the next question: *and what +does your environment check the project against, to know it is still what it +declared itself to be?* If the answer is a prose file nobody can query as data +or validate as a contract, you have an excellent vehicle headed to a +destination you never declared. At agent speed, a system with no declared +subject drifts faster than any human can watch. + +The answer to that question is already stated — it is the set of phrases +ontoref uses to define itself, rotating on [its own front page](/): + +> [What you leave stated, someone will be able to verify.](/) + +> [Knowing what you are is cheap. Knowing you still are is not — that must be +> verified.](/) + +> [A project with no verifiable reason for being isn't alive: it's being +> remembered.](/) + +What you only leave inside the harness, no one will be able to verify. diff --git a/site/site/content/blog/en/ontoref/a-harness-without-a-subject.ncl b/site/site/content/blog/en/ontoref/a-harness-without-a-subject.ncl new file mode 100644 index 0000000..99d98cf --- /dev/null +++ b/site/site/content/blog/en/ontoref/a-harness-without-a-subject.ncl @@ -0,0 +1,23 @@ +# Generated from a-harness-without-a-subject.md +# Schema: ../../../../../../../../../../jesusperezlorenzo/.local/share/rustelo/nickel/content/metadata/post_metadata.ncl +# Regenerate: nu scripts/content/md-to-ncl.nu --force + +let schema = import "../../../../../../../../../../jesusperezlorenzo/.local/share/rustelo/nickel/content/metadata/post_metadata.ncl" in + +schema.make_post { + id = "a-harness-without-a-subject", + title = "A harness without a subject: what harness engineering doesn't name yet", + slug = "a-harness-without-a-subject", + subtitle = "The AI harness is the word of the year: the five layers that wrap a model so it can do real work. But a minimal harness is a hundred lines, every vendor now ships one, and the advantage is moving one layer down — to the subject the harness consults.", + excerpt = "Harness engineering just named itself as a discipline: documentation as code, architectural constraints, layered verification, periodic consistency audits. All four pillars exist — in flat markdown, held up by manual discipline. This post concedes the whole argument (“the model is commodity, the harness is the advantage”) and adds the next step: the harness governs the verb — how a change is made — and names no subject to check it against. A verb without a subject cannot drift, because drift is precisely a subject diverging from its own declared self.", + date = "2026-07-19", + featured = true, + category = "ontoref", + tags = ["ontoref", "harness", "harness-engineering", "agents", "drift", "developer"], + sort_order = 9, + image_url = "/images/ontoref-harness-without-a-subject.webp", + graph = { + implements = ["witness-as-axis-seam", "drift-observation", "describe-query-layer", "self-describing"], + related_to = ["trust-is-an-output-not-an-input", "context-declared-not-filled"], + }, +} \ No newline at end of file diff --git a/site/site/content/blog/es/_index.ncl b/site/site/content/blog/es/_index.ncl index 7f6fb3f..875b644 100644 --- a/site/site/content/blog/es/_index.ncl +++ b/site/site/content/blog/es/_index.ncl @@ -1,6 +1,6 @@ # AUTO-GENERATED — do not edit manually # Scope: blog/es -# Updated: 2026-07-17T05:56:25Z +# Updated: 2026-07-19T04:50:00Z # Regen: nu scripts/content/generate-ncl-index.nu std.array.flatten [ diff --git a/site/site/content/blog/es/engineering/_index.ncl b/site/site/content/blog/es/engineering/_index.ncl index e20bbb4..d78d292 100644 --- a/site/site/content/blog/es/engineering/_index.ncl +++ b/site/site/content/blog/es/engineering/_index.ncl @@ -1,6 +1,6 @@ # AUTO-GENERATED — do not edit manually # Scope: blog/es/engineering -# Updated: 2026-07-17T05:56:25Z +# Updated: 2026-07-19T04:50:00Z # Regen: nu scripts/content/generate-ncl-index.nu [ diff --git a/site/site/content/blog/es/ontoref/_index.ncl b/site/site/content/blog/es/ontoref/_index.ncl index cb11ac9..1e5e831 100644 --- a/site/site/content/blog/es/ontoref/_index.ncl +++ b/site/site/content/blog/es/ontoref/_index.ncl @@ -1,9 +1,10 @@ # AUTO-GENERATED — do not edit manually # Scope: blog/es/ontoref -# Updated: 2026-07-17T05:56:25Z +# Updated: 2026-07-19T04:50:00Z # Regen: nu scripts/content/generate-ncl-index.nu [ + import "./a-harness-without-a-subject.ncl", import "./a-rule-without-a-trigger-is-a-sign.ncl", import "./ai-knowledge-tool-who-keeps-it-alive.ncl", import "./context-declared-not-filled.ncl", diff --git a/site/site/content/blog/es/ontoref/a-harness-without-a-subject.md b/site/site/content/blog/es/ontoref/a-harness-without-a-subject.md new file mode 100644 index 0000000..9d9ce21 --- /dev/null +++ b/site/site/content/blog/es/ontoref/a-harness-without-a-subject.md @@ -0,0 +1,163 @@ +--- +# Post metadata +id: "a-harness-without-a-subject" +title: "Un arnés sin sujeto: lo que el «harness engineering» aún no nombra" +slug: "un-arnes-sin-sujeto" +subtitle: "El arnés («harness») es la palabra del año: las cinco capas que envuelven al modelo para que haga trabajo real. Pero un arnés mínimo son cien líneas, cada proveedor ya envía el suyo, y la ventaja se está desplazando una capa hacia abajo: hacia el sujeto que el arnés consulta." +excerpt: "El «harness engineering» acaba de nombrarse como disciplina: documentación como código, restricciones arquitectónicas, verificación por capas, auditorías periódicas. Los cuatro pilares existen — en markdown plano, sostenidos por disciplina manual. Este post concede el argumento entero («el modelo es commodity, el arnés es la ventaja») y le añade el paso siguiente: el arnés gobierna el verbo — cómo se hace un cambio — y no nombra ningún sujeto contra el que comprobarlo. Un verbo sin sujeto no puede derivar, porque la deriva es exactamente un sujeto divergiendo de su propio yo declarado." + +# Publication info +author: "Jesús Pérez" +date: "2026-07-19" +published: true +featured: true + +# Categorization +category: "ontoref" +tags: ["ontoref", "harness", "harness-engineering", "agentes", "drift", "developer"] + +# Display +sort_order: 9 + +# Image (card thumbnail + in-post featured) +thumbnail: "/images/ontoref-harness-without-a-subject-es.webp" +image_url: "/images/ontoref-harness-without-a-subject-es.webp" +og_image: "/images/og/ontoref-harness-without-a-subject-es.png" +--- + + + + + Un arnés sin sujeto: lo que el «harness engineering» aún no nombra + + +Circula un término — «AI harness», el arnés — que está haciendo por 2026 lo que +*prompt engineering* hizo por 2022 y *context engineering* por 2025: darle nombre +a donde se decide de verdad el resultado. La definición que se está asentando +([webreactiva la resume bien](https://www.webreactiva.com/blog/ai-harness)) es +limpia: el arnés es **todo lo que envuelve al modelo para que haga trabajo real** +— herramientas, system prompt, gestión de contexto, permisos y bucles de +verificación. El modelo es el motor; el arnés, el vehículo completo. Y los números +que acompañan la tesis son serios: el mismo modelo pasando de 52,8 % a 66,5 % en +un benchmark cambiando solo el arnés; otro saltando de 6,7 % a 68,3 % cambiando +únicamente el formato de edición; LangChain midiendo saltos de 10–20 puntos en +tau2-bench con solo añadir perfiles de arnés específicos por modelo +([el repaso de DataCamp](https://www.datacamp.com/es/blog/agent-harness) los +recoge y deja la ecuación en canon: **agente = modelo + arnés**). De ahí la +consigna: *el modelo es commodity, el arnés es la ventaja competitiva*. + +Concedido. Entero. El arnés importa más que el modelo, y quien lo haya +comprobado con un agente real no necesita que se lo repitan. + +Ahora el paso que la consigna no da. + +## El arnés también se está volviendo commodity + +El propio argumento lo trae dentro: un arnés mínimo — leer fichero, listar, +editar — cabe en **menos de cien líneas**. Cada proveedor envía hoy el suyo, y +los de código abierto se cuentan por docenas. Cuando la pieza que era ventaja se +puede reproducir en una tarde, la ventaja no desaparece: **se desplaza una capa +hacia abajo**. La pregunta deja de ser «¿qué arnés ejecuta a tu agente?» y pasa a +ser «¿qué encuentra tu arnés cuando pregunta *qué es este proyecto y qué ha +decidido*?». + +Para la mayoría de los equipos, la respuesta honesta es: un montón de markdown. +Y no es una caricatura — es la definición del propio componente: cuando la +literatura del arnés enumera su «memoria y estado», lo que lista es ficheros, +logs y resúmenes. Estado sin tipo, prosa sin contrato. + +## Cuatro verbos, ningún sujeto + +Mira el vocabulario completo de la era de agentes: **orquestas** flujos, los +envuelves en **guardarraíles**, los ejecutas dentro de un **arnés**, **cosechas** +su salida de vuelta a memoria. Cuatro verbos, una gramática — y los cuatro +gobiernan el **acto**. Ninguno nombra un **sujeto**: algo que el proyecto haya +declarado ser, y que pueda comprobarse que sigue siendo cierto. + +Esa omisión no es un hueco del vocabulario; es su función. Un verbo sin sujeto +**no puede derivar**, porque la deriva es exactamente eso: un sujeto divergiendo +de su propio yo declarado a lo largo del tiempo. Lo que no puedes nombrar, no lo +puedes medir. Por eso el ecosistema puede enviar arneses cada vez mejores y +seguir sin respuesta para la única pregunta que importa a velocidad de agente: +*¿sigue siendo verdad lo que declaraste hace seis semanas?* La pregunta no es +expresable en la gramática elegida. + +El arnés es un instrumento **espacial**: contiene el acto en el momento en que +ocurre — este contexto, estos permisos, esta verificación, ahora. La deriva es +**temporal**: la separación lenta entre lo que un sistema dice ser y aquello en +lo que se ha convertido, medida en commits y sesiones, no en tokens. No se puede +levantar una valla contra el tiempo. + +## Los cuatro pilares, tipados + +Lo interesante del «harness engineering» como disciplina nombrada — Mitchell +Hashimoto le puso nombre en febrero de 2026 — es que sus cuatro pilares son un +mapa exacto del problema. Solo que cada pilar se practica hoy en su forma +informal: markdown plano sostenido por disciplina manual. Cada uno tiene una +forma tipada, y la diferencia entre ambas es si la coherencia **se espera** o +**se comprueba**: + +| Pilar del «harness engineering» | Forma informal | Forma tipada en ontoref | +|---|---|---| +| Documentación como código | `AGENTS.md` — prosa que el agente lee | Ontología consultable como datos: `describe` responde *qué es esto, qué puedo hacer, qué impacto tiene tocar X* | +| Restricciones arquitectónicas | Convenciones enunciadas en texto | Restricciones Hard/Soft de cada ADR, evaluadas por `validate-adrs`: una violación **rompe CI** | +| Verificación por capas | Hooks y revisión humana | Gates estructurales + testigo firmado: cada acto que muta el modelo emite un testigo; cada mutación es el depósito de un acto testificado | +| Garbage collection | Auditorías periódicas de consistencia | La deriva como valor de primera clase: un observador compara declaración contra artefacto y **propone** la corrección — nunca la aplica en silencio | + +La cuarta fila es la más reveladora. «Recolectar basura» cada cierto tiempo es +admitir que el sistema deriva y resignarse a barrerlo. Tratar la deriva como un +valor observable — algo que un proceso detecta, nombra y convierte en propuesta +de mutación revisable — es negarse a que la separación entre mapa y territorio +sea invisible mientras crece. + +## Tu arnés no compite con esto: lo consulta + +Aquí está el reparto de papeles, y conviene decirlo sin ambigüedad: **ontoref no +es un arnés y no pretende serlo**. No posee el bucle de herramientas, no ejecuta +nada por el modelo, no orquestará mejor a tus agentes. Es la capa que el arnés +encuentra cuando pregunta: el **sujeto** — un modelo tipado del proyecto: sus +decisiones con sus restricciones, su estado con sus condiciones de transición, sus +tensiones sin colapsar — que cualquier arnés puede consultar como datos y contra +el que cada cambio puede comprobarse. + +La taxonomía reciente distingue tres capas — «framework» (LangChain, CrewAI), +«runtime» (LangGraph, Temporal) y arnés (Deep Agents, los SDK de agentes) — y +ontoref no está en ninguna de las tres: es lo que las tres consultan. Hay además +una razón de peso para que viva fuera, y la aporta la propia literatura cuando +admite su tensión abierta: los resultados quedan **acoplados al perfil concreto +del arnés**, y cambiar de arnés o de modelo sale caro. Si el conocimiento del +proyecto vive dentro de ese perfil, cambiar de vehículo es perderlo — eres rehén +de tu arnés. Un sujeto declarado fuera de cualquier arnés es portable entre +todos ellos: responsable ante su modelo, rehén de ninguno. + +La relación es de invocación, no de réplica: el arnés (Claude Code, el que sea) +lleva un puntero vivo a la superficie gobernada; no copia su contenido, porque +una copia es la primera deriva. Y el protocolo se aplica a sí mismo el cuento: +el propio ontoref se describe con su propio protocolo — su ontología, sus ADRs y +su capa de reflexión son ontoref consumiendo ontoref. El sujeto que te pide +declarar es el que él mismo mantiene, y falla su propia CI cuando deja de ser +cierto. + +## La frontera honesta + +Quédate con tu arnés. Mejóralo: las cinco capas son reales y los números también. +Pero cuando la disciplina que acaba de nombrarse te diga que la ventaja está en +el entorno y no en el modelo, hazle la pregunta siguiente: *¿y contra qué +comprueba tu entorno que el proyecto sigue siendo el que declaró ser?* Si la +respuesta es un fichero de prosa que nadie puede consultar como datos ni validar +como contrato, tienes un vehículo excelente hacia un destino que nunca +declaraste. A velocidad de agente, un sistema sin sujeto declarado deriva más +rápido de lo que ningún humano puede vigilar. + +La respuesta a esa pregunta ya está dicha — son las frases con las que ontoref +se define a sí mismo, rotando en [su propia portada](/): + +> [Lo que dejas dicho, alguien podrá comprobarlo.](/) + +> [Saber lo que eres es barato. Saber que sigues siéndolo, no — eso hay que +> comprobarlo.](/) + +> [Un proyecto sin razón de ser verificable no está vivo: está siendo +> recordado.](/) + +Lo que solo dejas dentro del arnés, nadie podrá comprobarlo. diff --git a/site/site/content/blog/es/ontoref/a-harness-without-a-subject.ncl b/site/site/content/blog/es/ontoref/a-harness-without-a-subject.ncl new file mode 100644 index 0000000..0f0be07 --- /dev/null +++ b/site/site/content/blog/es/ontoref/a-harness-without-a-subject.ncl @@ -0,0 +1,23 @@ +# Generated from a-harness-without-a-subject.md +# Schema: ../../../../../../../../../../jesusperezlorenzo/.local/share/rustelo/nickel/content/metadata/post_metadata.ncl +# Regenerate: nu scripts/content/md-to-ncl.nu --force + +let schema = import "../../../../../../../../../../jesusperezlorenzo/.local/share/rustelo/nickel/content/metadata/post_metadata.ncl" in + +schema.make_post { + id = "a-harness-without-a-subject", + title = "Un arnés sin sujeto: lo que el «harness engineering» aún no nombra", + slug = "un-arnes-sin-sujeto", + subtitle = "El arnés («harness») es la palabra del año: las cinco capas que envuelven al modelo para que haga trabajo real. Pero un arnés mínimo son cien líneas, cada proveedor ya envía el suyo, y la ventaja se está desplazando una capa hacia abajo: hacia el sujeto que el arnés consulta.", + excerpt = "El «harness engineering» acaba de nombrarse como disciplina: documentación como código, restricciones arquitectónicas, verificación por capas, auditorías periódicas. Los cuatro pilares existen — en markdown plano, sostenidos por disciplina manual. Este post concede el argumento entero («el modelo es commodity, el arnés es la ventaja») y le añade el paso siguiente: el arnés gobierna el verbo — cómo se hace un cambio — y no nombra ningún sujeto contra el que comprobarlo. Un verbo sin sujeto no puede derivar, porque la deriva es exactamente un sujeto divergiendo de su propio yo declarado.", + date = "2026-07-19", + featured = true, + category = "ontoref", + tags = ["ontoref", "harness", "harness-engineering", "agentes", "drift", "developer"], + sort_order = 9, + image_url = "/images/ontoref-harness-without-a-subject-es.webp", + graph = { + implements = ["witness-as-axis-seam", "drift-observation", "describe-query-layer", "self-describing"], + related_to = ["trust-is-an-output-not-an-input", "context-declared-not-filled"], + }, +} \ No newline at end of file diff --git a/site/site/public/images/ontoref-architecture.svg b/site/site/public/images/ontoref-architecture.svg index 77a6294..04bad25 100644 --- a/site/site/public/images/ontoref-architecture.svg +++ b/site/site/public/images/ontoref-architecture.svg @@ -37,13 +37,13 @@ adrs/ - 73 records · 69 accepted + 74 records · 70 accepted typed constraints · warrant · ondaod reflection/schemas/ - 32 schemas · 8 forms - 47 migrations + 35 schemas · 11 forms + 48 migrations positioning/ @@ -70,7 +70,7 @@ reflection/modules/ · 38 Nushell modules - 29 DAG modes · describe · adr · validate · backlog · sync · graph · view · qa · … + 30 DAG modes · describe · adr · validate · backlog · sync · graph · view · qa · …