boshu2__agentops/docs/architecture/rpi-traversal.md

RPI traversal

This page owns the exact semantics of the RPI traversal — the standard path through the federated integration graph — and the semantic work-and-proof protocol it implements. AgentOps is the operations layer for agentic engineering; it is not CI, a Git workflow, a tracker, a queue, or an autonomous controller. Vocabulary lives in the ubiquitous language.

intent
  -> existing bead or caller source
  -> one bounded implementation experiment
  -> runtime-derived subject-manifest.v1 + check receipts
  -> one fresh independent validation
  -> PASS | FAIL | NOT_PROVEN
  -> report and stop

One traversal is one experiment. The caller, a Goal, or a factory decides whether to start another; the traversal itself never continues.

Roles

Role	Owns	Does not own
Caller	intent source, invocation, optional strategies, any later revision or delivery	semantic PASS unless acting in a fresh validator context
Plan	refining acceptance and write boundary in the existing source	a duplicate planning artifact, scheduling, ownership, readiness
Implement	one subject change and factual evidence	validation, repair loop, Git, closure, delivery
Validate	exact identity, independent judgment, optional durable evidence	subject edits, retries, next actions, release
RPI	one ordered dispatch and report	a controller around repeated invocations

One model may fill multiple roles across distinct contexts. PASS requires nonempty distinct author and validator context IDs and an explicit freshness attestation. The attestation is a declared trust fact, not cryptographic process isolation.

Intent source

Plan shapes one active behavior in the caller-owned bead, issue, or conversation. That source records:

• acceptance examples where they reduce ambiguity;
• non-goals and required evidence;
• write_scope.include and write_scope.exclude, including generated companions;
• a first acceptance command or artifact path;
• optional decomposition with no scheduling semantics.

The runtime stores the exact resolved source bytes under .agents/ao/intents/sha256/<digest>.intent and derives the acceptance digest from those bytes. This also makes conversation-only intent available to a fresh validator. The model does not author a second PlanPacket.

Owner, ready, claim, priority, attempt, wave, queue, lease, admission, next action, close, release, and delivery fields are outside the contract.

One bounded experiment

Implement consumes the resolved intent once. A behavior change captures a right-reason RED, makes the smallest coherent change that turns it GREEN, and refactors under the unchanged acceptance check. Docs-only and pure-refactor work record an honest pre-change baseline.

The runtime derives the author context, subject manifest, actual changed paths, coverage fact, and check receipts. These facts can be passed directly to Validate; the model does not transcribe a CandidatePacket. A failed check is evidence, not loop authority.

Content identity

subject-manifest.v1 is independent of Git. It contains normalized relative paths, file/symlink/deletion kinds, executable bits, content or target digests, declared roots and exclusions, an optional base-manifest digest, and one canonical manifest digest. Git commit/tree information may be attached as read-only metadata.

The pure helper lives at skills/validate/scripts/validate.py. It makes no Git, tracker, queue, network, release, or delivery call.

Fresh Validate

Validate recomputes subject identity, confirms intent-source continuity and complete changed-path coverage, compares actual changes with Plan scope, checks the evidence, and judges every acceptance criterion.

• Proven out-of-scope change: FAIL.
• Incomplete path coverage, subject mutation, digest mismatch, missing/colliding identities, or missing freshness: NOT_PROVEN.
• Complete evidence satisfying every criterion, with nonempty checked scope and evidence references: PASS.

not_checked names in-scope acceptance surface that this validation did not verify. PASS asserts that the whole declared acceptance surface was verified, so a PASS carries no not_checked entries and any entry makes the result NOT_PROVEN. That strictness never rewards deleting an honest caveat, because each kind of scope limit has a home that survives inside a PASS: a bounded proof of a criterion goes in criteria[].reason, a declared non-goal stays in the intent source (optionally restated as an evidence-backed boundary criterion), and residual risk goes in the caller-facing report. The full table lives in skills/validate/SKILL.md under Scope disclosure.

The validation result records criterion results, findings, evidence references, checked and not-checked surfaces, identities, and freshness. It carries no WARN, confidence, disposition, learning, owner, next action, retry, closure, release, or delivery state. Returning that result to the caller completes Validate; storage is not a precondition for semantic judgment.

When the caller requests machine-readable evidence or a declared downstream consumer requires it, Validate alone may persist verdict.v2. Default storage is .agents/ao/verdicts/sha256/<digest>.json; a caller may provide verdict_dir. The digest is SHA-256 over canonical JSON without artifact_digest. Writes are same-directory, flushed, fsynced, and atomically renamed. Exact existing content is idempotent. Conflicting content is an integrity failure and cannot produce PASS. Provenance may record a persisted verdict afterward, but ledger availability never affects validity.

Stop boundary and revision

RPI invokes Plan, Implement, and Validate at most once and then stops. A FAIL or NOT_PROVEN report does not repair, replan, consult a helper, escalate, or invoke a second phase. NOT_PLANNED and NOT_BUILT describe RPI progress only and are not verdict values.

If a caller wants another experiment, it updates the existing bead or caller intent and starts a new invocation. Any persisted verdicts and manifests remain durable evidence, but AgentOps does not require a model-authored revision packet. Changed acceptance is represented once in the intent source.

Optional ports

• Premortem, Postmortem, Council, and genie skills are optional judgment strategies selected by the caller.
• dispatch_once(explicit_disjoint_work, executor) may dispatch explicit disjoint work exactly once. It does not select, queue, persist, retry, validate, integrate, close, or deliver.
• Learn may later inspect collections of durable verdicts. It cannot alter a verdict, plan, or core result.
• Consumer repository Git, CI, merge, rollback, and release mechanisms operate after and outside this loop.