// semantic decision layer / typed judgments / explicit uncertainty

HowlInstinct ハウルインスティンクト // 2026

Before an agent acts, it should know why. HowlInstinct is decision infrastructure for autonomous systems: given state and a bounded question, it returns a typed judgment with explicit uncertainty and provenance.

AXIOM // CONFIDENCE IS NOT PERMISSION. HowlInstinct judges. Something else decides whether anything is allowed to happen as a result. There is no default threshold anywhere in this codebase — and a test parses the source to keep it that way.

[ GITHUB ] [ DOCUMENTATION ] [ EXPLORE THE HOWL ECOSYSTEM ]

LEAST POWER // CODE → INSTINCT → AGENT → HUMAN SYSTEM 0 → 1 → 2 → 3

00 // CODEIf deterministic code can answer it, HowlInstinct is the wrong tool.

01 // INSTINCTBounded semantic judgment with visible uncertainty.

02 // AGENTReasoning, synthesis, planning, generation — when needed.

03 // HUMANStill uncertain, or policy requires authority.

Why autonomous agents need a decision layer

Most questions a system asks itself are small: Is this an incident? Which team owns this? How risky is this change? Without a dedicated decision layer, answers tend to become brittle keyword rules nobody trusts — or full generative agents that return prose someone then has to parse.

Without Instinct

Inconsistent answers across providers
Overconfident prose treated as authority
Hard to audit or reproduce
Constraints stay implicit in prompts
if confidence > 0.95 { deploy() } appears somewhere

With HowlInstinct

Typed decisions: noul, choice, score, classify
Uncertainty stays visible (absence is not zero)
Durable decision receipts with hashes
Caller-owned escalation rules — never defaults
No vocabulary for deploy, approve, or delete

Decision flow (as implemented)

The request path is strictly ordered. Malformed batches are rejected before any provider is contacted; provider output is validated before a value enters a judgment.

[FLOW // ENGINE.DECIDE] docs/ARCHITECTURE.md

CONTEXT (state)
    │
    ▼
CONSTRAINTS / LIMITS     validate sizes, types, identifiers
    │
    ▼
OPTIONS / QUESTIONS      noul · choice · score · classify→choice
    │
    ▼
PROVIDER                 ask adapter (mock / jev / future)
    │
    ▼
EVIDENCE & UNCERTAINTY   provider_confidence ≠ instinct_margin
    │
    ▼
DECISION + OUTCOME       ACCEPTABLE_CONFIDENCE · LOW_CONFIDENCE · UNAVAILABLE · ERROR
    │
    ▼
RATIONALE / RECEIPT      hashes, provider, latency — not raw state by default
    │
    ▼
CALLER ACTION            caller applies policy / thresholds / escalation
                         HowlInstinct never acts

Decision types
Type	Question	Returns
`noul`	Bounded yes/no	P(yes). No separate confidence — the probability is the uncertainty signal.
`choice`	Pick one of a finite set	Selection, distribution, confidence
`score`	Place on an ordinal scale	Weighted level, legend, distribution, confidence
`classify`	Caller vocabulary	Lowered to `choice`; receipt keeps `compiled_to`

Principles

Evidence before action

Judgments leave receipts. Evaluation suites ask whether a decision class is trustworthy enough for a use — empirically.

Explicit constraints

Requests are strictly validated. Escalation fires only when the caller supplied a rule.

Uncertainty awareness

Absence is not zero. Provider confidence and instinct margin never share a name or silently convert.

Deterministic edges

Deterministic outside, probabilistic inside. Receipts are canonicalized and hashed.

Human escalation

Outcomes include low confidence and unavailable — never APPROVED or DENIED.

Bounded autonomy

Judgment is not action. No deploy, page, merge, roll back, approve, or delete vocabulary.

Provider independence

Nothing outside internal/provider names a vendor, model, endpoint, or wire format.

Reproducibility

Default mock is offline and deterministic. Same decision produces the same receipt digest.

Decisions are artifacts

A decision receipt is what survives a decision. It is designed to be stored, attached to an audit trail, and read back long after the state that produced it is gone.

[RECEIPT // howlinstinct.decision_receipt/v1] SCHEMA PUBLISHED

Decision receipt fields (representative):
  schema · decision_id · batch_id · timestamp
  question_id · decision_type · compiled_to?
  state_hash · question_hash          (content hashed, not retained by default)
  outcome · choice? · probabilities?
  provider_confidence? · instinct_margin?
  needs_escalation · provider · provider_model
  latency_ms · usage · correlation_id?

Deliberately absent by default: raw state, provider endpoint, invented zeros.

Real shape and examples: docs/DECISION_RECEIPTS.md. Callers who need state text can opt in with --retain-state.

Where Instinct sits

HowlInstinct answers bounded questions. Consumers decide what those answers mean. Sibling integration notes in this repository are proposed contracts — they have not been implemented in sibling repositories from this side.

[STACK // INTENT → JUDGMENT → TEAM → ORCHESTRATION → AUTHORITY] CONCEPTUAL

Intent / event
    │
    ▼
HowlInstinct     “Should we do this, and why?”
    │            (judgment + receipt — no permission)
    ▼
HowlForge        “Who should do it?”
    │
    ▼
HowlPlane        “How do we coordinate it?”
    │
    ▼
HowlFrame        “What is it allowed to do?”
    │
    ▼
Execution / ChangeOps / Proof / Relay / Board …

Shared boundary
HowlInstinct	The consumer
Judges	Decides
Reports uncertainty	Sets thresholds
Emits receipts	Applies policy
Knows nothing of consequences	Takes action

Integration notes · HowlForge · HowlPlane · HowlFrame · Hub

Provider independence

HowlInstinct does not depend on one vendor’s definition of reasoning. A provider is anything that can answer a bounded question through the Provider interface.

mock

Default offline lexical baseline. Deterministic. Ships with the repo. Not a semantic model.

jev

Any Jev-compatible /v1/systemone endpoint. No default hostname — configuration only.

Future adapters

Local providers and structured-LLM fallbacks fit the same interface without changing the public API.

Quick start

[QUICKSTART // OFFLINE MOCK DEFAULT]

go install github.com/howlcipher/howlinstinct/cmd/howlinstinct@latest
# or: make build   # -> build/howlinstinct

howlinstinct providers
howlinstinct doctor
howlinstinct decide --type noul \
  --state "All payment requests are returning HTTP 500 across every region." \
  --question "Is this an active production incident affecting customers?"

make demo   # event → judgments → receipts → mock policy consumer

Requires Go 1.26 or newer. Nothing else for the default mock path: no credentials, no network, no inference hardware. Philosophy: docs/PHILOSOPHY.md.

Status & repository

Bootstrap MVP — honest about what it is and is not.

Repository: github.com/howlcipher/howlInstinct
Go library + CLI with offline mock and jev adapter
Decision receipts schema published under schemas/
Sibling integrations documented as proposals, not completed wiring
No fabricated production readiness, benchmarks, or vendor lock-in claims