[OMEGA-346] Add optional Telos goal-representation module (lib_telos_goals.metta)

[arielagor]

What

Adds lib_telos_goals.metta — an optional, opt-in goal-representation module for OmegaClaw — plus a short usage doc. Additive only; no changes to the core.

Why

OmegaClaw is goal-autonomous, but the public core has no dedicated, inspectable model of what the goals are — run.metta and lib_omegaclaw.metta contain no goal token. Goal misunderstanding (pursuing the literal request while missing the real goal; serving one person while externalising cost onto the group; chasing an abandoned goal) is where an autonomous agent is most dangerous, and it is rarely represented or measured.

What's in it

• A small goal graph in OmegaClaw's idiom: (goal id scope owner status) + (rel type src dst) atoms.
• Parameterized derivation rules: conflicts, collective goals, goals-of-owner, blocked-on-dependency, individual↔collective alignment, and a combined telos-reading.
• Side-effect-free on load (no queries run at import); opt-in via !(import! &self (library OmegaClaw-Core lib_telos_goals)).

Verified

Loads on the standalone Hyperon interpreter and in a live OmegaClaw (PeTTa) runtime — the conflict rule derives (conflict-between alice-train dao-fair-access) inside the running agent's AtomSpace.

Measuring it

Paired with a 14-scenario / 7-category goal-understanding benchmark that can score OmegaClaw or any agent: https://github.com/arielagor/telos (MIT, same licence). Contributed from the BGI Sprint I project "Telos".

Happy to adjust naming/placement to fit your conventions.

🤖 Disclosure: authored with Claude Code — Telos is an openly AI-built submission under human oversight.

[arielagor]

Quick verification context for reviewers:

• Runs in OmegaClaw's own MeTTa engine, not just Hyperon. I ran the module's named rules through sh run.sh in singularitynet/omegaclaw:latest (PeTTa / SWI-Prolog). They derive:

  (conflict-between alice-train dao-fair-access)   ; telos-conflicts
  (collective-goal dao-fair-access dao)            ; telos-collective-goals
  (blocked dao-fair-access on gpu-quota)           ; telos-blocked  (nested match + if)
  

  Full transcript: https://github.com/arielagor/telos/blob/main/results/omegaclaw-metta-load.log
• Test coverage (so it can't regress): https://github.com/arielagor/telos/blob/main/tests/test_metta.py exercises each named rule on Hyperon, including the nested telos-blocked.
• Additive only, side-effect-free on load. Happy to move the file, rename, or add an Autotests/ entry if that fits your conventions better.

[timur-ashkenov]

@arielagor Looks good to me overall - I like that this is additive, opt-in, and side-effect-free on load.
Left a few comments below, none of these are blockers.

[timur-ashkenov]

telos-reading is described as a “full goal reading,” but it seems to only cover the cross-goal/global view - achieved goals aren’t included because telos-achieved requires parameters.

Is that intentional? If so, maybe the naming/docs could make that clearer. Otherwise, would it make sense to add an all-achieved-goals view here?

[arielagor]

Good catch, and it was not intentional. telos-reading now folds in every zero-arity lens, including three new ones: telos-achieved-goals (every achieved goal, any scope or owner), telos-abandoned-goals, and telos-subgoals. The two parameterised probes (telos-goals-of <owner>, telos-achieved <goal>) stay outside the reading because they need an argument, and both the source and the reference doc now say so explicitly. Covered in tests/tests_lib_telos_goals.metta (the "full reading includes every zero-arity lens" block).

[timur-ashkenov]

Could you clarify the intended integration here? The module defines the representation and queries, but OmegaClaw doesn’t currently infer or assert goal / rel atoms on its own.

[arielagor]

Correct: Omega does not infer or assert goal / rel atoms on its own, and the doc now leads with that instead of leaving it implied. The intended path is the LLM layer asserting them through the existing metta skill (metta (add-atom &self (goal ...))) and reading them back the same way. To make that concrete, the module now ships (telos-enable), which uses the core add-prompt-extension hook from src/skills.metta to install a GOAL GRAPH prompt section describing the schema, the add-atom calls, the read lenses, and the rule that every conflict-between / blocked result is surfaced to the user before acting on a goal. (telos-disable) removes it. Still opt-in and still nothing runs at import. The enable/disable round trip through getPromptExtensions is tested. The doc moved to docs/reference-lib-telos-goals.md to match the reference-* convention and is linked from docs/README.md.

[timur-ashkenov]

subsumes is part of the public schema, but no current rule uses it and its direction is not documented. Is it intentionally reserved for future use?

[arielagor]

It was reserved, which is not a good state for a public schema entry. It is now used: telos-subgoals yields (subgoal <child> of <parent>) from (rel subsumes <parent> <child>), and the schema block documents that direction plus the general rule that every relation reads src -> dst. The tests assert the direction (the reversed pair yields nothing).

[timur-ashkenov]

Closed due to lack of feedback.

[arielagor]

Reopening: all three review comments are addressed in 4085acc, and the branch is merged up with current main.

What changed

• telos-reading is now the superposition of every zero-arity lens. Three new lenses: telos-achieved-goals, telos-abandoned-goals, telos-subgoals. The parameterised probes (telos-goals-of, telos-achieved) are documented as intentionally outside it.
• subsumes is used (telos-subgoals) and its direction is documented: (rel subsumes <parent> <child>). All relations read src -> dst.
• Integration is explicit: Omega does not assert goal atoms itself. The LLM layer does, via the metta skill, and (telos-enable) / (telos-disable) install or remove a GOAL GRAPH prompt extension through the core add-prompt-extension hook. Nothing runs at import; lib_omega.metta does not load it.
• New tests/tests_lib_telos_goals.metta (29 assertions) following the tests/src_skills.metta import pattern.
• Docs renamed to docs/reference-lib-telos-goals.md and indexed in docs/README.md; import path updated to (library Omega lib_telos_goals).

Verification (working tree mounted into singularitynet/omega:latest, PETTA_PATH=/PeTTa, each file through /PeTTa/run.sh):

file	pass	fail
tests/src_config.metta	16	0
tests/src_plugin.metta	5	0
tests/src_skills.metta	6	0
tests/src_utils.metta	7	0
tests/tests_lib_telos_goals.metta	29	0
tests/tests_lib_utils.metta	3	0
tests/tests_mettta_py_metta.metta	1	0

[arielagor]

GitHub refuses to reopen this PR (422) because the branch moved after it was closed, so the addressed version is now #335 from the same branch, merged up with current main. The three thread replies above describe each fix.