Build on primitives, not parallel stores

A workflow should not invent a private “learning subsystem.” It should:

1. Emit feedback with explicit payload_type → POST /v1/humanos/feedback/events.
2. Read effective policy → GET /v1/humanos/policy/effective (includes learning).
3. Create proposals when adaptation requires it → POST /v1/humanos/learning/proposals with proposal_kind, payload (e.g. action_type for apply), optional explain metadata.
4. Move lifecycle and apply only when approved → PATCH …/proposals/:id, POST …/proposals/:id/apply.
5. Rollback when humans disagree → POST …/proposals/:id/rollback.
6. Publish packages with humanos.agent.v1 + generated learning_contract; validate locally with human humanos-manifest validate and CI with human marketplace review.

TypeScript (application SDK)

@human/client-sdk:

import { HumanClient } from '@human/client-sdk';

const client = new HumanClient({ apiKey: process.env.HUMAN_API_KEY! });
const effective = await client.humanos.getPolicyEffective();
await client.humanos.recordFeedbackEvent({
  payload_type: 'accepted',
  scope: 'user',
});

@human/sdk: client.humanosLearning exposes the same routes (getPolicyEffective, recordFeedbackEvent, createLearningProposal, applyLearningProposal, …).

Python / Go (agent runtimes)

Thin REST helpers ship beside the agent SDKs: human_agent.humanos_learning (Python) and human GetPolicyEffective, ApplyLearningProposal, … (Go) — same paths as above.

Monorepo developer guide

End-to-end walkthrough, curl templates, and CLI matrix: clone the repo and open docs/humanos-learning-developer.md.

Series

Part 1 · Part 5 · Primitives: CLI scaffolding · Learning rollback