feat: qualify transferable reward-memory experiences

loopx/capabilities/agent_turn_recall/core.py

@@ -45,7 +45,9 @@ def _recent_outcomes(quota_decision: Mapping[str, Any]) -> list[str]:
         ]
     )
     handoff = _mapping(quota_decision.get("handoff_readiness"))
-    candidates.append(_mapping(handoff.get("post_handoff_latest_run")).get("classification"))
+    candidates.append(
+        _mapping(handoff.get("post_handoff_latest_run")).get("classification")
+    )
     result: list[str] = []
     for value in candidates:
         text = _compact(value, limit=180)
@@ -121,9 +123,7 @@ def build_agent_turn_situation(
         "decision": _compact(quota_decision.get("decision"), limit=80),
         "selected_todo": selected,
         "recent_outcomes": _recent_outcomes(quota_decision),
-        "next_intent": _compact(
-            quota_decision.get("recommended_action"), limit=320
-        ),
+        "next_intent": _compact(quota_decision.get("recommended_action"), limit=320),
         "conflict_state": conflict_state,
         "status_health_ok": status_health_ok,
         "user_prompt_included": False,
@@ -231,6 +231,9 @@ def apply_guidance(
                 "candidate_ref": item.candidate_ref,
                 "target_class": item.target_class,
                 "content_summary": item.content_summary,
+                "experience": (
+                    dict(item.experience) if item.experience is not None else None
+                ),
             }
             for item in items
         ]

loopx/capabilities/content_ops/README.md

@@ -145,7 +145,10 @@ user's provider, and another Agent's private corpus is not a shared seed store.
    credentials and scope references in its owner-local configuration.
 3. Prepare one `scoped_feedback_reward_memory_event_v0` using the seed's
    `content_summary`, `target_class=procedural_experience`, and source kind
-   `reviewed_learning_card`. Use the seed id/version/digest as a stable source
+   `reviewed_learning_card`. Map the seed's applicability, observations,
+   procedure and limits into the required `procedural_experience_contract_v0`;
+   bind its evidence refs to the reviewed seed revision. Use the seed
+   id/version/digest as a stable source
    reference; fill workspace/project/user/peer and surface from the configured
    corpus. Set `requested_action_scopes=[]` and `raw_content_captured=false`.
    The configured standing policy still reviews the event. Set

loopx/capabilities/content_ops/experiences/x-composer-preflight-v1.json

@@ -41,7 +41,7 @@
     "query_hint": "X browser draft preparation: multi-link card selection, rich-text replacement and final readback",
     "instructions": [
       "Use the actor's explicitly configured corpus and provider; do not discover or reuse another Agent's private memory.",
-      "Review this seed against current artifacts and higher-priority instructions. Fill the existing scoped_feedback event with the configured scope, this content_summary and a seed/version/digest source reference.",
+      "Review this seed against current artifacts and higher-priority instructions. Fill the existing scoped_feedback event with the configured scope, this content_summary and a seed/version/digest source reference. Map applicability, an observed outcome and attribution from observations, future_behavior from the procedure, limits, and the reviewed seed ref into procedural_experience_contract_v0.",
       "Do not mark current_artifact_verified merely because the seed exists. Import as procedural_experience only after current verification through the existing candidate/review and ingest-event path.",
       "Require the existing provider write and exact readback receipt before claiming initialization. Deduplicate the same scoped seed revision; review updates rather than overwriting newer local experience.",
       "For automatic recall, configure the existing agent_workflow.turn_admission surface and include the actual X preparation work in the selected Todo. A configured provider alone does not connect a recall surface.",

loopx/capabilities/decision_context/outcome_feedback.py

@@ -260,6 +260,41 @@ def build_decision_outcome_feedback(
                     f"Decision: {accepted['summary']} "
                     f"Verified outcome: {verified_outcome['summary']}"
                 ),
+                "experience": {
+                    "schema_version": "procedural_experience_contract_v0",
+                    "applicability": [
+                        f"A future decision matches: {accepted['summary']}"
+                    ],
+                    "observed_outcome": verified_outcome["summary"],
+                    "attribution": (
+                        "The accepted decision and verified outcome are linked to "
+                        "the same exact-read evidence packet; rejected or stale "
+                        "claims were excluded from the attribution."
+                    ),
+                    "future_behavior": {
+                        "trigger": (
+                            "The same decision pattern recurs with a current source "
+                            "revision and no unresolved authority conflict."
+                        ),
+                        "action": (
+                            f"Re-evaluate the evidence before applying this decision: "
+                            f"{accepted['summary']}"
+                        ),
+                        "validation": (
+                            "Require an exact-read promoted claim and a verified outcome "
+                            "linked to the same evidence packet."
+                        ),
+                        "stop_condition": (
+                            "Do not reuse the experience when the source revision is "
+                            "stale, the outcome is unverified, or a conflict is unresolved."
+                        ),
+                    },
+                    "limitations": [
+                        "One verified outcome does not establish universal causality.",
+                        "Reuse requires current evidence and the original scope boundaries.",
+                    ],
+                    "evidence_refs": [evidence["packet_ref"], outcome["packet_ref"]],
+                },
                 "source": {
                     "source_kind": "verified_decision_outcome",
                     "source_ref": outcome["packet_ref"],

loopx/capabilities/reward_memory/README.md

@@ -179,10 +179,14 @@ path rather than a compatibility fallback.
 
 The production Codex CLI Turn performs recall after quota/Todo admission and
 accepts outcome ingestion only after independent validation, durable writeback,
-and quota settlement. A reflection must use `turn_reward_memory_reflection_v0`
+and quota settlement. A reflection must use `turn_reward_memory_reflection_v1`
 and include an exact configured surface, a distinct research/simulation/real/
 engineering source kind, and opaque evidence refs; an ordinary Turn summary is
-not evidence. Ambiguous provider commits and unverified readbacks remain in a
+not evidence. It also carries `procedural_experience_contract_v0` with
+applicability, observed outcome, attribution, complete future behavior,
+limitations, and the same evidence refs. Legacy v0 reflections remain
+audit-only and cannot become durable memory. Ambiguous provider commits and
+unverified readbacks remain in a
 mode-0600 Goal+Agent+event sidecar. The next executing Turn retries the same
 deterministic event before recall, so the provider can deduplicate it and LoopX
 can require exact readback. Explicit disable suppresses reconciliation and all
@@ -191,7 +195,7 @@ provider calls.
 The Codex App uses the same settlement boundary without copying the raw
 reflection into run indexes, rollout events, or public projections. For a
 Todo-bound accountable refresh, the caller may add
-`--reward-memory-reflection-json <turn_reward_memory_reflection_v0 JSON>`.
+`--reward-memory-reflection-json <turn_reward_memory_reflection_v1 JSON>`.
 LoopX stores that candidate only in a mode-0600 Goal+Agent+candidate sidecar and
 runs the exact completion-validation command already declared by that Todo. The
 validator must return `reward_memory_reflection_validation_v0` with the exact
@@ -261,7 +265,12 @@ The agent reviews the conversation before choosing what, if anything, to learn:
    `schema_version=scoped_feedback_reward_memory_event_v0`, a stable
    `feedback_ref`, actual `source`, `reasoning`, `guard_context`, compact
    `content_summary`, `target_class`, and exact identity/surface/revision/action
-   scope. Advisory classes require empty `requested_action_scopes`; allowed
+   scope. `procedural_experience` additionally requires a typed
+   `procedural_experience_contract_v0`: applicability, observed outcome,
+   attribution, future behavior (`trigger`, `action`, `validation`, and
+   `stop_condition`), limitations, and opaque evidence refs. A fact recap does
+   not satisfy this contract. Advisory classes require empty
+   `requested_action_scopes`; allowed
    policy scopes do not grant advisory memory action authority. Do not copy the
    fixture's actor or verified-guard assertions.
 4. Replace the hint's input placeholder and preview `ingest-event` without
@@ -286,7 +295,7 @@ the agent (or its applicable route); no extra store, queue or scheduler exists.
 | `run_bound_reward` | Explicit human judgment attached to one exact goal/run. | Evidence about that outcome only. Future influence requires compact candidate derivation and an activation policy; the overlay itself is not a standing instruction. | Append-only overlay; corrections and revocations append references instead of rewriting the judged run. |
 | `hard_policy` | Explicit user/repository/operator authority, or policy content inferred from verified owner/core-contributor evidence and bound to an existing project/action authority scope. | Constraint or veto inside the verified scope. Reasoning may infer policy meaning from rewards, preferences, current-artifact-verified experience, selected options, accepted/rejected outcomes, and maintainer corrections; it may not infer credentials, new publish/production scope, or cross-user/repository authority. | Active records retain actor, evidence, scope, and derivation provenance until superseded, revoked, or expired; temporary or weakly reinforced inference should expire or return to review. |
 | `soft_preference` | Explicit feedback, selected options, or later reviewed candidates scoped to a workspace/project and module-owned surface. | Advisory ranking or rewrite only. It cannot grant publish, merge, write, credential, or production authority. | Durable only after explicit review; editable, rejectable, supersedable, revocable, and retireable. |
-| `procedural_experience` | Revision-stamped trajectories, distilled experiences, maintainer corrections, accepted/rejected changes, and reviewed architectural learning, with repository/module/revision/applicability scope. | Advisory diagnosis, scope, routing, or validation guidance only after current-artifact verification. A training/evaluation case is evidence, not an executable instruction. Retrieval alone has zero patch authority. | Trajectories may be add-only; distilled or architectural experiences are supersedable. New source truth can stale, quarantine, refute, or retire them. |
+| `procedural_experience` | Revision-stamped trajectories, distilled experiences, maintainer corrections, accepted/rejected changes, and reviewed architectural learning. The typed experience contract preserves applicability, observed outcome, attribution, future behavior, limitations, and evidence refs. | Advisory diagnosis, scope, routing, or validation guidance only after current-artifact verification and experience-quality qualification. A fact-only summary or successful provider write is not experience evidence. Retrieval alone has zero patch authority. | New source truth or application evidence can mark an experience stale, harmful, refuted, superseded, or retired. Initial qualification means structurally reusable and evidence-bound; value remains unproven until application/outcome attribution. |
 | `working_context` | Either fresh execution state (`fresh_execution_context`) or a revisioned session-continuation summary (`session_working_memory`). | Supports only the current execution/session continuation. Neither subtype becomes reusable policy or grants action authority. Fresh source-of-truth reads outrank recalled material. | `fresh_execution_context` already exists in LoopX registry/state/todo/quota/checkout observations and is reused, not rebuilt. Session context remains bound to its session/archive revision. |
 
 Every durable record must name `source`, `scope`, `authority`, `confidence`,
@@ -459,13 +468,32 @@ repository write authority, publish/production scope, or cross-project
 authority. Out-of-scope, conflicted, stale, raw, or unmodelled input is
 `guard_blocked` before any provider call.
 
+For `procedural_experience`, deterministic guards first require the complete
+typed experience contract. Missing or malformed future behavior, limitations,
+or evidence binding is rejected before the provider is called. The complete
+contract participates in `candidate_ref`, survives the active envelope, and is
+injected into recall guidance. Legacy fact-only procedural records are not
+recallable. This is a qualification gate, not a claim of proven utility:
+application receipts and verified outcome attribution still decide whether an
+experience was helpful, neutral, harmful, or should be retired.
+
 The command then composes deterministic `candidate_ref` deduplication, standing
 policy acceptance, active-envelope construction, declared-provider `sync`, and
-one exact-corpus/surface function-boundary recall. A
+one exact-corpus/surface function-boundary readback. For
+`procedural_experience`, it also performs a destination-surface
+`business_recall` using the applicability and future-behavior fields, without
+the candidate id in the query. The recalled record must match both the
+candidate and experience digests. This prevents an exact-id storage check from
+being mistaken for evidence that a lesson can be found where decisions use it. A
 `reward_memory_ingest_receipt_v0` reports `activated` and
 `memory_available_for_recall=true` only when resource ref, candidate ref, and
-canonical content digest all match. Provider unavailability, pending commit,
-or readback mismatch fails open and does not block the caller's normal work.
+canonical content digest all match, the class-specific experience-quality gate
+passes, and any required destination recall succeeds. A destination miss stays
+`recall_unverified` for bounded reconciliation rather than becoming active.
+`exact_readback_verified=true` alone proves persistence, not experience quality,
+discoverability, or utility. Provider unavailability, pending commit, readback
+mismatch, or destination-recall miss fails open and does not block the caller's
+normal work.
 `observed_at` is the immutable first-observed event timestamp and must be reused
 on retries. The provider target binds both standing-policy and candidate
 digests so a policy revision cannot silently reuse an older activation.