Federated from workspace · PL-004 · zaixos-intelligence-platform/DECISION_MODEL.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

PL-004 Decision Model

Platform: ZIP · Principle: Recommendation before execution

---

Purpose

Define the decision and recommendation lifecycle — how ZIP evaluates intelligence decisions, produces recommendations, and transitions through approval without performing domain execution.

---

Terminology

Term	Definition
Decision definition	Product extension rule — when and what to evaluate
Decision candidate	Runtime match of a definition against current signals
Reasoning artifact	Evidence-backed hypothesis — immutable
Execution plan	Step graph with gates — preview-safe
Recommendation bundle	Human-consumable package for approval
Approval session	Stateful HITL workflow
Handoff manifest	Immutable execution instruction for product adapter

“Decision” in ZIP is intelligence decision — not business authorization. Business authorization occurs in the approval session.

---

Decision definition schema

Registered in product manifest decisionDefinitions:

Field	Description
key	Unique decision identifier
priority	Evaluation ordering
trigger	schedule · event · signal_threshold · manual
signalKeys	Required signal inputs
objectiveKey	Links to objective registry
cooldownMinutes	Minimum interval between evaluations
enabled	Boolean

ZIP owns evaluation machinery. Product owns definition content.

---

Lifecycle state machine

Recommendation bundle

draft → pending_validation → validated → pending_approval → approved → handed_off → closed
                                                          ↘ rejected → closed
                                                          ↘ expired → closed
draft → cancelled

Transition	Guard
draft → pending_validation	Plan attached
pending_validation → validated	All validation ports pass
validated → pending_approval	Governance tier allows issue
pending_approval → approved	Approval session granted
approved → handed_off	Handoff manifest published
handed_off → closed	Outcome recorded or timeout
pending_approval → rejected	Approver denied
pending_approval → expired	Expiry policy elapsed

Approval session

open → pending_quorum → granted | denied | expired | escalated

---

Evaluation pipeline

Trigger (schedule | event | manual)
    → Load decision definitions (manifest)
    → Filter by trigger + cooldown + enabled
    → Load signal snapshots
    → Produce decision candidates
    → For each candidate (priority order):
          Reasoning pipeline
          Planning pipeline (if actionable)
          Validation pipeline
          Recommendation assembly
    → Emit zip.recommendation.issued
    → Open approval session (if tier ≥ T2)

Multiple candidates may coexist. Conflicts resolved by priority and confidence scoring.

---

Recommendation bundle contents

Section	Artifact reference
Executive summary	Generated plain-language summary
Evidence	Signal snapshot IDs + reasoning artifact
Plan	Execution plan artifact revision
Assets	Generated asset manifest (PL-003 jobs)
Confidence	Score + explainability metadata
Approval policy	Required roles, tier, expiry
Cost estimate	PL-003 provider cost + product budget port

---

Explainability requirements

Every issued recommendation must include:

1. Signals — which metrics triggered evaluation
2. Reasoning — hypothesis and supporting evidence chain
3. Alternatives considered — ranked options rejected (when generative reasoning used)
4. Confidence — numeric score with method identifier
5. Risk flags — compliance or feasibility warnings
6. Cost — estimated resource consumption

---

PRD-001 pattern alignment

PRD-001 AutonomousOperations @ v3.2 provides the reference product implementation:

PRD-001	ZIP decision model
DecisionRegistry	decisionDefinitions extension slot
DecisionEngine	ZIP decision evaluator runtime
DecisionReasoningEngine	ZIP reasoning context
RecommendationApprovalEngine	ZIP approval context
RecommendationExecutionEngine (preview)	ZIP planning + validation (preview-only)

Future consumer integration delegates product contract to ZIP via compatibility adapters — not during bootstrap.

---

Cross references

• AUTONOMY_MODEL.md
• LEARNING_MODEL.md
• EXTENSION_MODEL.md

---

Version history

Version	Date	Change
1.0	2026-07-01	Initial decision model — bootstrap