HumanOS policy: why this threshold is policy, not vibes
The number that was never supposed to be a constant
Somewhere in every agent stack, confidence becomes a float and floats become politics. This essay is about dragging that politics into the light: confidence / review policy and scoped config resolution are how HUMΛN keeps “magic routing” from becoming “mystery nudging.”
For the operator-facing narrative of the same spine, see Safety at business speed.
From literal to legible
The HumanOS public route once treated 0.7 as folklore. Now humanos_org_policies.policy_json can carry confidence_review.fourth_law_confidence_threshold, merged with defaults in @human/humanos. GET /v1/humanos/policy/effective exposes the effective threshold and learning_requires_approval so operators can answer “why did this escalate?” without reading TypeScript.
That is inspectability: the default is still gentle, but the override is documented, scoped, and tested.
Magic first, power second — for real
Magic means a tenant routes work without assembling a policy graph by hand. Power means when they tighten the Fourth Law to 0.55 for a regulated division, the system behaves — it does not silently ignore JSON because nobody wired the field.
Trust expectations
Use cases:
- Given a compliance officer auditing escalations, when they call policy/effective, then they see the numeric threshold and learning gate — not a shrug.
- Given a product team testing a stricter org, when they PUT policy JSON via
/v1/humanos/policy/org, then routing pre-checks honor the new threshold on the next request. - Given an engineer fearing “silent preference drift,” when they read learning_requires_approval, then they know durable adaptation stays behind explicit rules (learning and rollback).
Spirit: The system should feel confident when it acts and honest when it is unsure — never the reverse.
Extended narrative — precedence you can test
Org JSON is not a second religion sitting beside code defaults; it is an overlay with deterministic merge rules. That matters because “we set it in the DB” must never mean “we forked semantics.” Precedence tests spell out cases: empty overlay, partial finance, nested safety domains, blocklist growth, task-context slices, and learning approval toggles. They are boring tests — on purpose. Boring tests are what keep your policy story from becoming folklore.
Admin write lands as PUT /v1/humanos/policy/org, guarded by humanos:admin, merging JSONB keys so operators do not accidentally wipe unrelated domains. Reads stay on GET /policy/effective, returning the merged object a router already trusts. Explainability bundles carry a policy_applied_id derived from the org row timestamp (or a default sentinel), so “why this threshold” has a stable handle for support and audit — the same field on artifact explain.
Trust expectation: When someone asks “why 0.42?” the answer cites policy_applied_id + merged fields — not “the model felt like it.”
Given / When / Then (use case 4)
Given two overlays applied sequentially, when operators merge finance ceilings, then unspecified finance keys remain from defaults — no silent nulling.
Given / When / Then (use case 5)
Given a compliance officer, when they compare GET effective JSON to an explain bundle factor, then Fourth Law text matches the merged threshold.
Given / When / Then (use case 6)
Given a malicious client sending non-object policy_json, when PUT validates the body, then they receive field-scoped 400 — no partial writes.
Go deeper
- Product: HumanOS · Governance
- Docs: HumanOS concepts · Provenance
- Community: Safety at business speed · Artifacts and explainability · Learning, rollback, and tuning
HumanOS primitives program — Part 2 of 6