HumanOS artifacts and the “why am I seeing this?” bundle
Chat ends; work products persist
Agents generate text all day. Artifacts are what remains when the conversation should have a draft, a review, a delivery, and an audit trail. Wave 4 is the story of taking work seriously — P7 — and explaining it without dumping logs — P6.
Lifecycle as contract
draft → in_review → approved → delivered (with side states like rejected / failed) is not bureaucracy for its own sake. It is respect: humans know when they are being asked to own an output versus skim a suggestion.
Explainability is not log tailing
GET /v1/humanos/artifacts/:id/explain returns a bundle: summary, factors with source labels (policy | preference | inference | fact), related WorkObjectRef entries, and confidence metadata including policy_applied_id from org policy storage (or a default sentinel when only code defaults apply).
Use cases
- Given a memo drafted by an agent, when it enters
in_review, then reviewers see lineage and policy factors — not a wall of JSON. - Given an auditor, when they fetch explain, then they can separate fact from inference in the factors list.
- Given a PM, when they compare chat output to artifacts, then they can articulate which outputs are deliverables under governance.
Spirit: Warm default, cold audit trail — friendly summaries with a door to the receipts.
Extended narrative — FSM as empathy
Artifacts are where chat stops being vapor and becomes work product. If every PATCH silently accepts arbitrary state jumps, reviewers learn not to trust the badge. The lifecycle FSM returns 409 with INVALID_ARTIFACT_TRANSITION — not to annoy integrators, but to protect humans from “approved yesterday, draft today” ghost stories.
Explainability ties artifacts to policy without dumping YAML: factors carry source: policy for Fourth Law threshold context, and related_work_refs can include linked Captures. That is how we keep P6 from becoming a log grep exercise.
Trust expectation: A reviewer trusts the badge because the server enforces transitions — not because the UI pinky-swears.
Given / When / Then (use case 4)
Given an integrator attempting draft → approved skip, when PATCH fires, then 409 lists allowed next states.
Given / When / Then (use case 5)
Given an artifact tied to a Capture, when explain is fetched, then related_work_refs includes both artifact and capture ids.
Given / When / Then (use case 6)
Given support staff comparing two orgs, when they read policy_applied_id in the bundle, then they know which org policy revision applied.
HumanOS primitives program — Part 4 of 6