Add governed repo-local learning and playbook update flow for agents

[mdheller]

Context

The SourceOS Agent Reliability Standard requires that durable agent learnings become governed memory, not untraceable chat residue.

MemoryMesh should own repo/project/user/org memory provenance and playbook reconciliation for agent reliability.

Scope

Implement governed memory update flow for agent sessions:

• agent identifies a durable operational learning
• agent proposes a memory/playbook update as a diff or artifact
• destination scope is explicit: repo, project, user, org, enterprise
• conflicting playbook entries are reconciled, not duplicated
• high-impact memory updates require human review
• accepted updates record source session, reason, approver, and affected repo/policy/runtime surface

Repo-local targets

Support standardized repo-local paths:

SOURCEOS.md
AGENTS.md
.sourceos/memory/
.sourceos/workflows/
.sourceos/policies/
.sourceos/handoff/

Acceptance criteria

• AgentPlane/guardrail-fabric sessions can emit proposed memory update artifacts.
• MemoryMesh can ingest and classify proposed learnings by scope.
• Playbook updates are reviewable and provenance-linked.
• A repo can distinguish accepted durable knowledge from transient session notes.

Non-goals

• Do not allow silent mutation of governance memory.
• Do not require cloud sync for local memory capture.

[mdheller]

Coordination note: learning representations / governed memory

Checked for existing channels before opening anything new. This issue is the correct primary Memory Mesh lane for the learning-representations work. Do not create a parallel “learning representations” channel here.

Existing adjacent channels to reuse

• SocioProphet/memory-mesh#22 — primary repo-local governed learning / playbook update flow.
• SocioProphet/memory-mesh#18 — governed memory lifecycle for agentic graph sync.
• SocioProphet/memory-mesh#19 — SourceOS State Integrity-backed memory durability, provenance, invalidation.
• SocioProphet/memory-mesh#21 — memory substrate health and lane reporting.
• SocioProphet/memory-mesh#17 — OpsHistory context-pack contract.
• SocioProphet/ontogenesis#26 — SHIR / knowledge induction / evidence / projection-loss semantic fabric.
• SocioProphet/ontogenesis#38 — reasoning-failure ontology and EvidenceReceipt vocabulary lane.
• SocioProphet/sociosphere#315 — agent DevOps mesh, scheduler/kernel model, representation envelope, coherence/barrier vocabulary.
• SocioProphet/agentplane#83, #85, #90, #93, #103 — context intake, operation plane, substrate trust gates, scheduling, and typed failure traces.
• SocioProphet/sherlock-search#6, #52 — search packets preserving evidence, provenance, freshness, authority, and policy fields.

Placement decision

The learning-representation work should be split by ownership, not duplicated:

1. Memory Mesh owns durable memory lifecycle and governed writeback.

   • Agent learnings remain proposals until reviewed.
   • Durable writeback requires explicit scope, evidence, policy decision, review status, and destination path.
   • No silent global memory mutation.

2. Ontogenesis owns semantic vocabulary and SHIR alignment.

   • Claim, Evidence, Receipt, Context, Assertion, Projection, ProjectionLossReport, and related semantic classes belong there.
   • Memory Mesh should reference these terms/contracts rather than redefining ontology semantics.

3. Sociosphere owns cross-repo scheduling, queueing, topology, and coherence/barrier coordination.

   • It should coordinate representation envelope fields and state transitions across repos.
   • It should not own memory storage or ontology semantics.

4. AgentPlane owns execution traces and evidence emission.

   • Agent sessions emit proposal/evidence artifacts.
   • Memory Mesh receives proposal packets; it does not become the agent runtime.

5. Sherlock owns discovery/index packets, not source of truth.

   • Search packets should preserve evidence refs, provenance refs, policy ceilings, freshness, and authority refs.

Communications-systems-derived extension to fold into this issue

The MIT 16.36 communication systems pass adds a useful discipline layer:

• Sampling contract: memory/event proposals should state source observation window, sampling/summary basis, and freshness.
• Framing contract: every proposed learning must carry explicit frame boundaries: source session, destination, learning type, evidence refs, policy refs, review state, redaction state, and writeback state.
• Compression contract: summaries/playbook updates must preserve provenance, authority, unresolved conflicts, and retention class.
• Detection contract: detector/classifier-derived learnings must identify signal/noise assumptions, confidence, and abstention/uncertainty where applicable.
• Error/provenance contract: proposals must distinguish checksum/schema validity from semantic truth and policy approval.
• Queueing contract: review/update flows should be measurable as queues: arrival rate, service time, WIP, blocked state, stale proposals, promotion latency.

Recommended next implementation slice for this issue

Extend the existing agent-learning proposal / governed memory update path rather than introducing a new schema family.

Suggested additions:

• Add optional observationContext to the agent learning proposal or a companion memory-object schema:

  • sourceWindowRef
  • observedAt
  • validTime
  • freshnessPolicy
  • samplingBasis
  • compressionBasis

• Add optional representationEnvelope:

  • frameType
  • authoritySource
  • sourceEpoch
  • validityWindow
  • cacheState
  • dirtyState
  • revocationStatus
  • correlationId
  • evidenceRefs
  • provenanceRefs
  • policyContext
  • writePolicy

• Add optional learningSignal when the proposed learning came from a detector/ranker/evaluator:

  • signalClass
  • noiseAssumption
  • confidence
  • abstentionBoundary
  • detectorRef
  • evaluationReceiptRefs

• Add queue/ops fields or derived metrics in docs:

  • proposalArrivedAt
  • reviewRequiredBy
  • blockedReason
  • promotionLatency
  • staleAfter

Acceptance refinement

This issue should be considered complete only when the repo-local governed learning flow can represent:

• a raw agent/session observation;
• a review-only learning proposal;
• evidence/provenance/policy refs;
• review state and writeback state;
• durable accepted memory/playbook update;
• conflict/supersession/revocation path;
• and at least one example showing compressed learning with preserved source/evidence/authority.

This preserves the existing channel structure and folds the new learning-representations doctrine into the Memory Mesh lane instead of creating an overlapping architecture track.

[mdheller]

Coordination note: learning representations / governed memory

Checked for existing channels before opening anything new. This issue is the correct primary Memory Mesh lane for the learning-representations work. Do not create a parallel “learning representations” channel here.

Existing adjacent channels to reuse

• SocioProphet/memory-mesh#22 — primary repo-local governed learning / playbook update flow.
• SocioProphet/memory-mesh#18 — governed memory lifecycle for agentic graph sync.
• SocioProphet/memory-mesh#19 — SourceOS State Integrity-backed memory durability, provenance, invalidation.
• SocioProphet/memory-mesh#21 — memory substrate health and lane reporting.
• SocioProphet/memory-mesh#17 — OpsHistory context-pack contract.
• SocioProphet/ontogenesis#26 — SHIR / knowledge induction / evidence / projection-loss semantic fabric.
• SocioProphet/ontogenesis#38 — reasoning-failure ontology and EvidenceReceipt vocabulary lane.
• SocioProphet/sociosphere#315 — agent DevOps mesh, scheduler/kernel model, representation envelope, coherence/barrier vocabulary.
• SocioProphet/agentplane#83, #85, #90, #93, #103 — context intake, operation plane, substrate trust gates, scheduling, and typed failure traces.
• SocioProphet/sherlock-search#6, #52 — search packets preserving evidence, provenance, freshness, authority, and policy fields.

Placement decision

The learning-representation work should be split by ownership, not duplicated:

1. Memory Mesh owns durable memory lifecycle and governed writeback.

   • Agent learnings remain proposals until reviewed.
   • Durable writeback requires explicit scope, evidence, policy decision, review status, and destination path.
   • No silent global memory mutation.

2. Ontogenesis owns semantic vocabulary and SHIR alignment.

   • Claim, Evidence, Receipt, Context, Assertion, Projection, ProjectionLossReport, and related semantic classes belong there.
   • Memory Mesh should reference these terms/contracts rather than redefining ontology semantics.

3. Sociosphere owns cross-repo scheduling, queueing, topology, and coherence/barrier coordination.

   • It should coordinate representation envelope fields and state transitions across repos.
   • It should not own memory storage or ontology semantics.

4. AgentPlane owns execution traces and evidence emission.

   • Agent sessions emit proposal/evidence artifacts.
   • Memory Mesh receives proposal packets; it does not become the agent runtime.

5. Sherlock owns discovery/index packets, not source of truth.

   • Search packets should preserve evidence refs, provenance refs, policy ceilings, freshness, and authority refs.

Communications-systems-derived extension to fold into this issue

The MIT 16.36 communication systems pass adds a useful discipline layer:

• Sampling contract: memory/event proposals should state source observation window, sampling/summary basis, and freshness.
• Framing contract: every proposed learning must carry explicit frame boundaries: source session, destination, learning type, evidence refs, policy refs, review state, redaction state, and writeback state.
• Compression contract: summaries/playbook updates must preserve provenance, authority, unresolved conflicts, and retention class.
• Detection contract: detector/classifier-derived learnings must identify signal/noise assumptions, confidence, and abstention/uncertainty where applicable.
• Error/provenance contract: proposals must distinguish checksum/schema validity from semantic truth and policy approval.
• Queueing contract: review/update flows should be measurable as queues: arrival rate, service time, WIP, blocked state, stale proposals, promotion latency.

Recommended next implementation slice for this issue

Extend the existing agent-learning proposal / governed memory update path rather than introducing a new schema family.

Suggested additions:

• Add optional observationContext to the agent learning proposal or a companion memory-object schema:

  • sourceWindowRef
  • observedAt
  • validTime
  • freshnessPolicy
  • samplingBasis
  • compressionBasis

• Add optional representationEnvelope:

  • frameType
  • authoritySource
  • sourceEpoch
  • validityWindow
  • cacheState
  • dirtyState
  • revocationStatus
  • correlationId
  • evidenceRefs
  • provenanceRefs
  • policyContext
  • writePolicy

• Add optional learningSignal when the proposed learning came from a detector/ranker/evaluator:

  • signalClass
  • noiseAssumption
  • confidence
  • abstentionBoundary
  • detectorRef
  • evaluationReceiptRefs

• Add queue/ops fields or derived metrics in docs:

  • proposalArrivedAt
  • reviewRequiredBy
  • blockedReason
  • promotionLatency
  • staleAfter

Acceptance refinement

This issue should be considered complete only when the repo-local governed learning flow can represent:

• a raw agent/session observation;
• a review-only learning proposal;
• evidence/provenance/policy refs;
• review state and writeback state;
• durable accepted memory/playbook update;
• conflict/supersession/revocation path;
• and at least one example showing compressed learning with preserved source/evidence/authority.

This preserves the existing channel structure and folds the new learning-representations doctrine into the Memory Mesh lane instead of creating an overlapping architecture track.

[mdheller]

Tranche update after PR #28 merge

PR #28 is merged. It added the first learning-representation envelope to AgentLearningProposal without creating a parallel memory channel.

Merged contract additions:

• observationContext for bounded observation, valid time, freshness, sampling basis, and compression basis.
• representationEnvelope for frame type, authority source, source epoch, validity window, cache/coherence state, evidence/provenance refs, policy context, and write policy.
• learningSignal for signal class, detector/noise assumption, confidence, abstention boundary, detector ref, and evaluation receipt refs.
• reviewQueue for proposal arrival, blocked reason, stale/required-by timestamps, and promotion latency.
• docs/architecture/learning-representation-envelope.md documenting placement, invariants, and communications-system mapping.

All PR #28 workflows passed before merge: validate-locks, python-validation, agent-learning-proposal, validate-runtime, test-finance-source-of-truth, and deploy-assets-validation.

Next tranche for this same issue

Do not open a parallel governed-learning channel. Continue this issue by adding the accepted/rejected/revoked lifecycle examples and queue metrics around the merged envelope.

Scope

1. Add accepted durable memory example.

   • Should represent a reviewed and approved AgentLearningProposal promoted into durable repo-local memory.
   • Must preserve original proposal id, source session, evidence refs, policy decision refs, reviewer/approval ref, destination path, and writeback receipt.

2. Add rejected proposal example.

   • Should show a learning that remains unpromoted because evidence is insufficient, policy denies it, or it conflicts with an authoritative playbook entry.
   • Must preserve rejection reason and no-writeback state.

3. Add revoked/superseded memory example.

   • Should show a previously accepted memory invalidated by newer evidence, policy revocation, or playbook replacement.
   • Must include revocation/supersession refs and tombstone semantics rather than silent deletion.

4. Add conflict/reconciliation example.

   • Should demonstrate two proposed playbook updates targeting the same repo-local path and how duplicate/conflicting entries are reconciled.

5. Add review queue metrics fixture or docs section.

   • Required fields: proposal arrival time, pending age, blocked reason, stale count, promoted count, rejected count, superseded count, promotion latency.
   • Keep this as fixture/docs unless there is already a metrics code path to extend safely.

Acceptance criteria

• Existing make validate-agent-learning-proposal remains green.
• New examples validate under existing or added validators.
• Examples prove the system can distinguish transient proposal, accepted durable memory, rejected proposal, revoked memory, and superseded memory.
• No durable writeback occurs without policy decision refs, approval refs, and writeback refs.
• No raw sensitive payloads are embedded.
• The docs explicitly preserve ownership boundaries: Memory Mesh owns lifecycle; Ontogenesis owns semantics; AgentPlane emits execution evidence; Sociosphere owns queue/coherence coordination; Sherlock indexes discovery packets.

@copilot please implement this as the next focused contract-only PR against SocioProphet/memory-mesh. Keep runtime behavior out of scope unless an existing validator needs a small fixture-aware extension.