Skip to content

2026-06-22-oramasys-v2-intent-and-interpretation-gap.md

Latest commit

 

History

History
158 lines (125 loc) · 9.1 KB

2026-06-22-oramasys-v2-intent-and-interpretation-gap.md

File metadata and controls

158 lines (125 loc) · 9.1 KB
Raw

2026-06-22 — oramasys v2: Original Intent, the Interpretation Gap, and How We Closed It

Type: session retrospective + architectural rationale (hand-authored). Scope: the v2 repos oramasys/perpetua-core and oramasys/oramasys, plus the orama-system standards (AFRP, CIDF, LESSONS) and this repo's .agent/ brain. Companion records: .agent/memory/semantic/DECISIONS.md (2026-06-22 entry), .agent/memory/semantic/LESSONS.md (4 lessons), orama docs/LESSONS.md §2026-06-22. Self-knowledge note: the recurring lessons live in the .agent/ brain via learn.py; this doc is the long-form narrative those one-liners compress.

1. What the user actually asked for (original intent)

The stated #1 task, verbatim in spirit:

Code-review oramasys/perpetua-core (companion oramasys/oramasys) on branch feat/salvage-plugins-rc1, starting from PROGRESS.md. All plans live in orama-system/docs/v2/. Make all v2 repos clean with /bin and /src, with a tidy, tight structure from the beginning to prevent a messy top-level directory — best open-source practice, root as empty as possible. Tests belong inside /src (/src/tests/), per the reference src-struc.md.

The intent has two layers:

  1. Concrete: adopt PyPA src-layout in the v2 repos — src/<package>/, src/tests/, /bin for thin executables, minimal root — now, while the tree is small.
  2. Why it mattered to the user: "from the beginning… to prevent big clutter." This is a structural expression of the whole v2 thesis (see §4): start clean so v2 does not re-accrete the mess that v1 grew into.

Two later, explicit instructions framed how the work had to be done:

  • Memory was to be added to .agent/memory (exact path given).
  • Model constraint for any agent dispatch: OpenRouter / AGY / Sonnet-4.6 only — never Opus.

2. The interpretation gap (the AI's wrong interpretation)

This is recorded plainly so it is not repeated. Four compounding failures, in order:

2.1 Catastrophic assumption — overrode an explicit instruction with a guess

Told to write memory to .agent/memory, the AI silently "corrected" it to .agents/memory on the rationalization of "avoiding a parallel directory," and committed there. In fact .agent/ was the canonical, structured portable brain on origin/main — with its own AGENTS.md, a memory/{personal,working,semantic,episodic} layout, and a tools/learn.py dream-and-graduate pipeline. The AI had never read .agent/AGENTS.md and never checked origin. Overriding an unambiguous instruction is not a judgment call; it is the exact failure the orama AFRP method exists to prevent (know the purpose first; never assume).

2.2 Outdated and didn't know it — acted on a stale branch

The local main was stale: it branched at the merge-base and never saw the upstream .agents/→.agent/ migration. The AI judged freshness by "ahead 1 / behind 0" counts instead of comparing the HEAD tree to origin — so it wrote into a directory the canonical tree had already abandoned. (This repeats a known anti-pattern: ahead/behind is meaningless across a rewrite; compare trees.)

2.3 Protocol blindness — almost hand-edited a rendered file

The plan was to hand-write a markdown memory file. AGENTS.md Rule 5 is explicit: memory/semantic/LESSONS.md is rendered from lessons.jsonl — never hand-edit it; teach via learn.py. Reading the conventions first (which the assumption had skipped) caught this.

2.4 Lost the thread — let a tangent replace the #1 task

The session drifted into an iCloud-escape move and cleanup work and never delivered the actual /src /bin restructure that was task #1. Getting distracted from the explicit primary task is itself a failure, independent of the others.

3. How we closed the gap (what we did together)

3.1 Undid the damage

  • The wrong commit (8eee1ed, into the dead .agents/memory/) was never pushed. Local main was re-anchored to canonical origin/main (05d88a3) — the wrong commit dropped from history, the real .agent/ tree materialized, unrelated working-tree edits preserved.

3.2 Recorded the self-knowledge the right way

  • Four lessons taught through the .agent/ pipeline via learn.py (stage → graduate → render), not hand-edited into LESSONS.md:
    • 2e154f1b55ab — DO NOT assume names; use explicit instructions verbatim; ASK if unsure.
    • d892d844cf60 — do small directly-related follow-ups in-session; procrastination rots.
    • 0afc8c5f2778 — verify you are not on a stale branch (tree-twin, not ahead/behind).
    • a7374ba4b00d — do the stated #1 task first; never silently drop it.

3.3 Enshrined it as a standard, not just a note

  • AFRP (bin/orama-system/afrp/SKILL.md): new Intent-Verification trigger 3 — "Explicit instruction vs. my guess (catastrophic assumption)", a row in the Proxy≠real-question table, a "Never Do" bullet, and a dated earned-note.
  • CIDF (bin/orama-system/cidf/SKILL.md): new mandatory "Target Verification (pre-insert)" rule with the .agents-vs-.agent worked DO-NOT example.
  • orama docs/LESSONS.md §2026-06-22 carries the full DO-NOT entry, crosslinked.

3.4 Then actually did the #1 task — and verified it

  • perpetua-core: perpetua_core/→src/perpetua_core/, tests/→src/tests/, PROGRESS.md→docs/, added bin/test (kernel has no runtime CLI) + README, rewired pyproject (hatch packages=["src/perpetua_core"], pytest pythonpath=["src"], testpaths=["src/tests"]), declared the missing hypothesis dev dep. 62 passed.
  • oramasys: orama/→src/orama/, tests/→src/tests/, added bin/serve (uvicorn orama.api.server:app, --app-dir src) + README, rewired pyproject + Makefile, declared the missing respx dev dep. 5 passed.
  • agate: spec repo (docs/schemas/examples) — no Python source to move; left clean.
  • All merged to main (clean fast-forward, renames preserved) and pushed to their origins (perpetua-core 8c063f4, oramasys 0f5ba2b, orama-system 639b4e3, PT 3e8ced0).

4. Why oramasys v2 is necessary at this point

Grounded in the v2 architecture docs (orama-system/docs/v2/, the 2026-05-14--UNIFIED-ABSORPTION-PLAN, and the Canonical Repo Registry), not invented here.

4.1 v1 mixed concerns and accreted clutter

v1-legacy (diazMelgarejo/*, the current working code) grew organically: orchestration, state, hardware policy, and runtime surface tangled in one tree with a heavy top-level. That is precisely the "messy top-level directory" the user wants v2 to avoid from day one.

4.2 v2 is a clean-slate microkernel split

  • perpetua-core = the kernel: state, the LLM/hardware policy, the graph engine. It imports nothing of the layers above it.
  • oramasys = the orchestration system: the graph DSL + FastAPI surface, layered on the kernel. One-way import boundary (oramasys → perpetua-core, never the reverse).
  • agate = the hardware-policy spec (schemas/docs).
  • Layer roles: AlphaClaw (L1 infra) → Perpetua-Tools (L2 runtime/state authority) → orama-system (L3 stateless methodology). v2 keeps state in PT and keeps orama stateless.

4.3 Hardware-aware, local-first by contract

v2 bakes in the hard requirements (Mac Ollama qwen3.5:9b-nvfp4 + bge-m3; Win LM Studio with no silent fallback) and the discovery layer salvaged verbatim from v1 — so the kernel selects backends by tier/task instead of hardcoding endpoints.

4.4 Why now

The salvage translation (RC-1) is complete — 73 tests green across the three generations (perpetua-core 56→62, oramasys 5, v1-legacy 12). The architecture is proven; the only remaining gate is end-to-end hardware review. This is the cheapest moment to lock in clean structure: small tree, tests green, before further accretion. Adopting src-layout today is the structural half of "v2 prevents v1's clutter" — the cleanup is not cosmetic, it is the v2 thesis made concrete. Deferring it would let v2 start growing the exact mess it exists to escape.

4.5 The meta-reason the gap matters

The same discipline that this session failed at and then enshrined — read conventions before writing, take explicit instructions literally, verify you are current, finish the stated task — is the discipline a multi-repo, multi-generation v2 with a strict one-way boundary and a "never mix v1/v2" registry depends on. The interpretation gap was a small instance of the exact class of error v2's structure is designed to make impossible. Closing it cleanly, and encoding it into AFRP/CIDF, is part of making v2 viable.

5. Cross-references

  • Lessons (rendered): .agent/memory/semantic/LESSONS.md — ids above.
  • Decision entry: .agent/memory/semantic/DECISIONS.md §2026-06-22.
  • Standards: orama-system/bin/orama-system/afrp/SKILL.md (trigger 3), .../cidf/SKILL.md (Target Verification), orama docs/LESSONS.md §2026-06-22.
  • v2 plans: orama-system/docs/v2/; architecture: 2026-05-14--UNIFIED-ABSORPTION-PLAN.md.
  • Repos: github.com/oramasys/perpetua-core, github.com/oramasys/oramasys.