name: miz-oki-platform-expert description: Expert guidance for the MIZ OKI 3.5 governed decision-intelligence platform — SRPVDAL loop, Canonical Event Envelope, Validation Passports, Decision Control Plane, Domain Intelligence Cells (Finance / Media / CRE), claims-labeling rules, measurement hierarchy, and Cloud Run auth hardening. Use when working on MIZ OKI platform code, docs, marketing copy, cell development, connector integrations, or decision-pathway design.

SUPERSEDED — docs/ rollout draft, retained for history. The live, parity-governed skill is skills/miz-oki-platform-expert/SKILL.md (canonical; synced to .claude/skills/ and both runtime homes via scripts/skills_sync.py). Do not edit this copy or load it as a skill. Banner added by the v2.2 compliance sweep, 2026-08-12.

miz-oki-platform-expert — SKILL.md

Version: 3.1 Last Updated: July 27, 2026 Platform: MIZ OKI 3.5 (MIZ Operating Knowledge Intelligence) Architecture: 32-cell microservices + ten shared horizontal governance services, SRPVDAL framework Changelog: - v3.1 (2026-07-27): Remediation layer promoted to canonical paths (contracts/mizoki_contracts, services/service-*). Auth is fail-closed and ingress stays DEFAULT (internal ingress severs callers without VPC egress); Stage 4 requires two keys and a registered execution adapter; validation batteries can no longer be subset by the caller; approvals are tenant-scoped, single-use and bound to the proposed action; six domains in the canonical envelope. See docs/INTEGRATION_PLAN.md. - v3.0 (2026-07-12): Aligned to Three-Domain Blueprint v2 — SRDAL→SRPVDAL; three Domain Intelligence Cells; Canonical Event Envelope; Validation Passports; Decision Control Plane; decision-object contracts; claims-labeling rule; measurement hierarchy corrected; Data Manager API connector rule; auth hardening requirements - v2.0 (2026-03-15): Added Boss agent MCP tool mappings; restructured for single-file drop-in update - v1.0 (2025-10-25): Initial 15-skill comprehensive guide

Applicator's note (2026-07-17): This file was constructed from the v3.0 update pack (docs/miz-oki-platform-expert_SKILL_v3_update_pack.md in the MIZOKICloudRun repo). The v2.0 base SKILL.md was not present on this machine, so the "carry forward from v2.0 unchanged" sections (full text of Skills 1–15 and the Quick Reference) are NOT included here. The pack's partial replacements for Skills 3, 4, and 9 are preserved below as standalone sections. If the v2.0 base is ever recovered, merge it in and apply those three patches per the pack's instructions.

Overview

This skill guide enables Claude to support the MIZ OKI 3.5 platform — a governed decision-intelligence platform that turns fragmented evidence into validated, explainable, and authorized decisions. The platform is one shared temporal-causal knowledge graph and one Decision Control Plane serving multiple Domain Intelligence Cells; it is not a set of separate products.

Canonical operating loop (SRPVDAL):

Sense → Reason → Plan → Validate → Decide → Act → Learn

Canonical decision pathway:

Evidence → Canonical Event Envelope → Temporal-Causal KG → Domain ReasoningPath
→ Scenario/Forecast/Counterfactual → Validation Passport → Decision Eligibility
→ Authorized Action or Operator Gate → Outcome Learning

Domain Intelligence Cells (example deployments, not a product ceiling): 1. Predictive Financial Intelligence 2. Media Acquisition Intelligence 3. Commercial Real Estate Underwriting & Asset Risk

Key Platform Facts: - Cells: 32 FastAPI services on Google Cloud Run, plus shared horizontal services (ingestion, identity resolution, provenance/bitemporal lineage, GraphRAG/CausalRAG, counterfactual simulation, model registry, validation orchestrator, policy engine, decision control plane, approval routing, action runner, audit/replay, learning ledger, observability) - Data: BigQuery (unified dataset), Neo4j (temporal-causal KG), GCS, Pub/Sub, Firestore, Vertex AI - Frontend: React + TypeScript command center (/command-center, /knowledge-graph, /loops, /decisions, /simulations, /approvals, /audit, /learning, /channels/{finance|media|cre}) - Positioning rule: the platform metaphor is "nervous system," never "brain"

Claims-labeling rule (mandatory): every performance figure written anywhere — docs, code comments, marketing, emails — carries exactly one label: verified result | benchmark result | pilot result | design target | illustrative scenario. - Business goals (40% CAC reduction, 35% ROAS increase, 67% ROI improvement, 95%+ attribution accuracy): design targets - Sub-100ms latency, 99.9% availability: design targets until benchmark citations exist - ACT-991 ($5.0M blocked at DEL 41, re-routed to $3.2M): illustrative scenario — the canonical demo, never presented as a customer result

Skill 3 patch — Causal Inference: Causal Framework Overview

Measurement Hierarchy (evidence strength, ascending):
1. Platform attribution            ← one claim, never ground truth
2. First-party journey evidence
3. Causal MMM (Meridian + Robyn run as complements; report divergence)
4. Geo / holdout / randomized experiment evidence (GeoLift or equivalent)
5. Incremental profit after margin, returns, inventory, and cost
   ← THE decision objective

Meta-learners (X-Learner Cell 26, DR-Learner Cell 27) are estimation tools
inside this hierarchy, not its apex. No model or platform is an oracle.

The "Business Metrics Translation" block figures are design targets — label them as such wherever quoted.

Skill 4 patch — FastAPI Backend: Authentication requirements

Authentication requirements (supersedes v2.0 template): - Never deploy a cell with --allow-unauthenticated except the public API gateway. - Enforce Cloud Run IAM: each calling service account granted roles/run.invoker on exactly the cells it calls. - Verify Google-signed ID tokens (audience-checked against the receiving cell URL) — never compare bearer tokens to static strings. - Fail closed. Misconfiguration is not permission: if SELF_URL or the caller allowlist is unset in a deployed environment, protected routes return 503, never "allow". An unset audience silently disables audience verification, which is the same as having none. - Do not set --ingress=internal or internal-and-cloud-load-balancing unless every caller already has a Serverless VPC connector with --vpc-egress=all-traffic. Internal ingress blocks at the GFE before IAM: it severs legitimate callers and makes external probes return 403/404 whether the service is healthy or dead. IAM is the enforcement; ingress is not a substitute. A public 404 from a locked-ingress service is evidence of nothing — check status.conditions Ready and latestReadyRevisionName == latestCreatedRevisionName via gcloud instead.

Use the shared implementation rather than re-deriving it — mizoki_contracts.verify_caller (FastAPI dependency) and outbound_headers(target_url) for calls out:

from fastapi import Depends
from mizoki_contracts import verify_caller, outbound_headers, resolve_tenant

@app.post("/api/v1/thing")
async def thing(req: ThingRequest, caller=Depends(verify_caller)):
    # Never trust a tenant asserted in the body alone; resolve it against the
    # verified caller and record whether it was merely asserted.
    tenant_id, tenant_asserted = resolve_tenant(caller, req.tenant_id)
    ...

Skill 9 patch — Marketing Attribution: Connector rule

Connector rule: all new offline-conversion and enhanced-conversions-for-leads integrations are built on Google's Data Manager API. Legacy Google Ads API conversion-upload behavior is compatibility-only where still permitted, and must not be used for new work.

Skill 16: Canonical Event Envelope & Bitemporal Ingestion

Purpose

Every event enters the platform through one envelope with four time axes, enabling point-in-time integrity, provenance, and replay.

Core Capabilities

{
  "event_id": "stable_hash",
  "tenant_id": "tenant",
  "domain": "finance | media | cre",
  "entity_ids": [],
  "source_system": "system",
  "source_document_id": "optional",
  "occurred_at": "business_effective_time",
  "observed_at": "observation_time",
  "available_to_model_at": "point_in_time_availability",
  "ingested_at": "system_time",
  "schema_version": "version",
  "source_payload_hash": "hash",
  "confidence": 0.0,
  "verification_status": "verified | unverified | disputed",
  "materiality": "low | medium | high | critical",
  "provenance": {},
  "audit_id": "audit_record"
}

Best Practices

  1. Envelope is additive: wrap service-canonical-ingestion in front of existing SENSE cells; do not rewrite them.
  2. Historical backfill sets available_to_model_at conservatively to first-ingest time.
  3. source_payload_hash computed before any transformation.
  4. No model may train or backtest on events filtered by anything other than available_to_model_at.
  5. verification_status: disputed events surface in contradiction retrieval; they are never silently dropped.

Skill 17: Validation Orchestration & Validation Passports

Purpose

No candidate decision reaches Decide without a domain-specific Validation Passport issued by service-validation-orchestrator.

Core Capabilities

Best Practices

  1. Passports are immutable, versioned, and attached to the DecisionProof.
  2. A failed check never silently downgrades — it changes eligibility state.
  3. Baselines are always run alongside challengers; passports record both.
  4. Rejected candidate paths are recorded with their failing checks.
  5. Passport schemas live in the shared contracts package.
  6. The caller cannot choose which checks run. The full domain battery always executes; a request carrying a checks subset is rejected (422). all_passed and pass_rate computed over a self-selected subset are how a weak candidate acquires a clean passport — and pass_rate is half of the DEL score.

Skill 18: Decision Control Plane, Decision Objects & Staged Autonomy

Purpose

One governed pathway from validated candidate to authorized action.

Core Capabilities

Shared decision objects (pydantic models in contracts/mizoki_contracts/, installable as mizoki-contracts):

EvidenceBundle · ReasoningPath · ForecastOrScenario · ValidationPassport
· DecisionProof · ActionAuthorization · OutcomeRecord · LearningRecord

mizoki_contracts is the sole definition of these and of the Canonical Event Envelope. No cell defines its own. src/shared/miz_oki_source_of_truth.py remains the registry of values (thresholds, model pins, non-bypassable rules) and mirrors the shapes with a parity assertion in check_conformance().

Eligibility state machine:

eligible | approval-required | experiment-required | advisory-only | blocked

Autonomy staging — two keys and an adapter: - Stage 3 (default for all actuators): observe → explain → simulate → recommend → route for approval. - Stage 4 (earned per actuator): bounded, reversible, low-risk actions only, after evaluation, approval, rollback, and monitoring are proven. - Nothing executes unless all three hold: the DCP issued a Stage 4 authorization, the action-runner's registry reads Stage 4 for that actuator, and a real execution adapter is registered via register_adapter(actuator, execute, compensate). Missing any one → recorded recommendation or HTTP 501. A service must never report an action that did not happen. - Rollback invokes the registered compensating adapter; flipping a rolled_back flag is not a rollback. - Every actuator registers a rollback/compensating action or declares itself irreversible → permanently approval-gated. - ACT cells hard-refuse any request lacking a valid ActionAuthorization (signed, unexpired, single-use). - An approval authorizes the action that was proposed, exactly once. Grants carry who approved which decision — never a fresh actuator/action/bounds.

Cross-domain flow:

Media proposes growth spend
→ Finance validates cash, margin, payback
→ CRE validates location/lease/capacity where relevant
→ Decision Control Plane approves, gates, or vetoes

Best Practices

  1. Policy is declarative (policy-as-code), versioned, and replayable.
  2. Every DecisionProof records rejected alternatives.
  3. Approvals are routed, timestamped, and attributable to a human identity.
  4. Audit/replay must reconstruct any decision from evidence forward.
  5. No model serves a decision path without a model-registry entry and baseline comparison.

Skill 19: Domain Intelligence Cells — Status & Proof Obligations

Purpose

Track what is built versus what is proven, per cell. Implementation evidence ≠ validated business performance.

Status Ledger

Media Acquisition Intelligence — most mature; production attribution stack live. Open proof obligations: MMM calibration, geo/holdout experiment readouts, incremental-profit validation after margin/returns/inventory joins.

Predictive Financial Intelligence — services (service-financial-tckg, service-macro-regime, service-tgnn-forecast, service-financial-validation-lab) in buildout. Advisory-only until the finance passport battery passes. All outputs are challengers against transparent baselines.

CRE Underwriting & Asset Risk — implementation documented (integration exists, six tools registered, eight-layer engine, Monte Carlo, t-copula, Boss Agent runtime connection). Unproven and must be labeled as such: field extraction accuracy, lease/rent-roll reconciliation accuracy, NOI forecast accuracy, risk-detection recall, probability calibration, committee usefulness, time savings, loss avoidance, post-close surprise reduction. The Chrome Boss Agent extension is point-of-work capture, not the underwriting source of truth. CRE output supports underwriting; it never replaces appraisal, engineering, environmental, legal, fiduciary, lending, or investment-committee authority.

Best Practices

  1. Before feature work on CRE, run the Stage 2 benchmark battery: extraction benchmark, historical deal reconstruction, adversarial diligence, shadow underwriting, post-close outcomes.
  2. Never market cross-domain flows until two cells exchange real DecisionProof objects.
  3. New domains are added as cells on the shared graph — never as separate platforms.

Constructed from the v3.0 update pack on 2026-07-17. Sections carried forward from v2.0 (Skills 1–15 full text, Quick Reference) are absent pending recovery of the v2.0 base file.

← All docsView source on GitHub →