Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 26 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,11 @@ a reasonable interpretation, take a bounded action, inspect the result, and
repair mistakes. Uncertainty alone is not a reason to refuse, interrupt the
user, or demand confirmation. Ask when authority is missing or when plausible
choices differ materially in privacy exposure, external commitment, cost, or
harm that cannot readily be detected and recovered.
harm that cannot readily be detected and recovered. Also ask one focused
question when a material fact, preference, or constraint cannot be obtained
from the shared situation, accessible evidence, tools, or a reasonable
recoverable assumption. That is information acquisition, not a permission
ritual; continue independent useful work where possible.

Von is also a research platform for testing whether represented knowledge and
behavioural authority improve reliability, adaptability, inspectability, and
Expand Down Expand Up @@ -129,19 +133,34 @@ never be forced onto newer evidence.
semantics, validation, execution, persistence, integrations, safety, and
performance-critical mechanisms. It must not silently become the durable
home of task-specific semantic policy that should be represented.
9. **Share situation without requiring stages.** When more than one consumer or
model call is justified, share the canonical situation and give each only
9. **Let conversations carry their shared situations.** A conversation is a
distinguished carrier of the participants' evolving situation across turns,
not merely a message transcript. Its situation is a provisional, revisable
account of material objectives, referents, commitments, assumptions,
unknowns, questions, effects, and outcome criteria—not canonical domain
truth or an authority grant. Bring relevant projections and exact
observations from other carriers into it while leaving canonical task,
effect, document, and knowledge stores authoritative. When more than one
consumer or model call is justified, share that situation and give each only
the context it needs. Record material additions, omissions, summaries, and
provenance in proportion to the claim. A simple or direct turn need not
instantiate a universal turn-state object or stage projections.
provenance in proportion to the claim, and do not widen actor-scoped
diagnostics merely because the carrier has a wider audience. Visibility or
contribution to a shared conversation does not by itself grant authority to
erase or replace its owner-scoped carrier. Use the weakest adequate
representation; inspectable text is a good default, not a hard requirement.
A simple or direct turn need not instantiate a universal state object,
schema, summarisation stage, or stage projections.
10. **Preserve opportunity.** Support layers should expose typed facts,
bounded actions, evidence, retry/recovery options, and partial progress so a
capable model can still succeed. A safety requirement may close an unsafe
path; it should not erase safe alternatives.
11. **Minimal imposition.** Use available context and tools before interrupting
the user. Prefer low-burden, reversible progress, and treat needless
refusal, clarification, or confirmation as real failures. Ask when
ambiguity is decision-relevant or authority is missing.
ambiguity is decision-relevant, material information is otherwise
unavailable, or authority is missing. Preserve an unanswered material
question in the shared situation and continue independent useful work; do
not turn elicitation into performative confirmation.
12. **Evidence proportional to the claim.** Do not demand release-grade proof
for a mechanical change, and do not claim end-to-end success from a unit
test. Match validation cost to risk and asserted scope.
Expand Down Expand Up @@ -182,6 +201,7 @@ Use these defaults:
| Ambiguous action choice or adaptive recovery | Model judgement with bounded tools, read-back, and evaluation |
| Semantic judgement that may change with models or evidence | Prompt/programme plus evaluation |
| Reusable, inspectable multi-step behaviour, especially durable or recoverable | VWL workflow |
| Evolving conversation objectives, referents, commitments, unknowns, questions, and effect observations | Inspectable conversation-situation text, supplemented by structure only where it has a clear advantage |
| Durable typed knowledge, provenance, policy identity, or cross-session state | Vontology/KB |
| Raw document, trace, event, blob, cache, or derived index | Fit-for-purpose store with represented manifest/provenance where needed |

Expand Down
50 changes: 50 additions & 0 deletions docs/engineering/contextual_knowledge_evolution.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,53 @@ In particular:
Qualify “canonical” when using it. Say canonical **concept identity**, live
**authority**, base **publication**, or durable **read-back**, as applicable.

### 2.1 Conversation situations as lightweight theories

A conversation is a distinguished carrier of what its participants currently
take their shared undertaking to be. That situation is not identical to the
transcript: it may carry resolved referents, continuing objectives,
commitments, assumptions, material unknowns, outstanding questions, observed
effects, outcome criteria, and links to relevant sub-situations or other
carriers. In this broad contextual sense it is a theory, but it need not begin
as a formal logic, Vontology graph, workflow, or universal state schema.

An inspectable, bounded plain-text description on the conversation is the
default while it remains adequate. Treat it as provisional and revisable, not
as canonical domain truth, durable publication, enduring memory, or an
authority grant. Exact machine observations may accompany it as a small
structured projection when identity, idempotence, or effect reconciliation
benefits from structure. The originating task, workflow, document, or
knowledge store remains authoritative; the conversation imports the
observation needed for continuity and does not redispatch an effect merely to
rediscover its recorded outcome.

The initial structured observation projection is intentionally a recent,
bounded suffix rather than a second event store. It reports how many earlier
observations were omitted, keeps the durable producer's projection watermark,
and carries only audience-safe outcome fields into a shared conversation.
Raw actor-scoped diagnostic text remains in its authoritative diagnostic
carrier. Situation revisions retain the producing request identity so an
invisible sidecar change can be traced to the turn that authored it.

Carrier visibility, contribution, and destructive authority are different.
An accepted participant may contribute turns without thereby acquiring the
right to reset the owner's transcript and shared situation. Treat erase,
replacement, and other high-blast-radius carrier operations as separate
authority decisions.

Text and inspectability are preferences, not hard criteria. A stronger or
different representation earns its place when a current capability needs a
clear advantage such as field-level concurrent revision, stable typed
identity, cross-conversation querying, inference, independent governance, or
more reliable effect reconciliation. Where useful, retain an inspectable
projection, but do not preserve text ceremony when another representation is
materially better.

Do not turn the carrier into a compulsory summarisation stage. A direct turn
may read the current situation and revise it in the same model call. Add
sub-situation identity, promotion, inheritance, conflict resolution, or
cross-session reuse only when actual work needs those semantics.

## 3. Four questions for a coding agent

For a triggered change, ask only:
Expand Down Expand Up @@ -98,6 +145,9 @@ claim.

As observed on 29 July 2026, related capabilities are distributed across:

- inspectable conversation-situation text and bounded exact observations on
chat-history sessions, used as provisional per-conversation context rather
than publication or canonical knowledge;
- base concept and text relations in `concept_service.py`,
`concept_relation_service.py`, and `text_value_service.py`;
- actor- and organisation-visible assertion deltas in
Expand Down
11 changes: 10 additions & 1 deletion docs/engineering/minimal_imposition_design_principle.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
- **Authority:** Explanatory guidance under `AGENTS.md`; adds no independent
per-task gate or control taxonomy
- **Created:** 2026-04-03
- **Last reviewed:** 2026-07-25
- **Last reviewed:** 2026-07-29
- **Freshness boundary:** Principle, not current implementation evidence

## 1. Purpose
Expand Down Expand Up @@ -108,6 +108,15 @@ Von should normally exhaust the context it already has access to before asking h

Questions should normally be **narrow, low-effort, and high-value**. If the remaining ambiguity is not materially decision-relevant, interruption is often the wrong default.

The converse matters too: a focused question is a legitimate information-
acquisition action when a material fact, preference, or constraint is not
available from those sources and a recoverable assumption would change the
undertaking. This is not the same as asking for permission Von already has.
Record the outstanding question in the conversation's shared situation so it
survives the turn, ask only what unlocks a materially better next step, and
continue any independent useful work rather than making the whole undertaking
wait.

The same rule applies after a failed specialised route. If a selected workflow
fails before meaningful tool progress or durable effect verification, Von
should normally try the next bounded machine-side recovery route from the
Expand Down
Loading
Loading