arifos-deploy

---
name: arifos-deploy
description: "arifOS sovereign deployment: static hub, docs, runtime, and machine files. Use when deploying arifOS estate surfaces. Encodes deployment philosophy, estate roles, CI/CD policy, machine file invariants, and rollback doctrine. Triggers: deploy, build site, CI/CD, publish, machine files, llms.txt, static hub, Cloudflare, GitHub Pages, VPS runtime."
---

# arifOS Deploy — Sovereign Deployment Doctrine

Ditempa Bukan Diberi. Every deployment is a thermodynamic state transition. Only deploy what is proven reversible.

---

## Core Invariants (Never Change)

These are constitutional-level constraints. No tool, command, or convenience may violate them.

### The Three Surfaces

```
arifOS-fazil.com     → Hub (identity, summaries, machine discovery)
arifos.arifOS-fazil.com → Docs (full technical content)
arifOS:8080/mcp     → Runtime (constitutional tool execution)
```

**Role rule:** Hub never hosts full docs content. Docs never hosts hub content. Runtime is never a static site. These boundaries never swap.

### Machine Discovery Invariants

Machine-readable files MUST be at root-level stable canonical paths:

```
/llms.txt               → LLM context injection (text/plain)
/robots.txt             → Crawler control
/sitemap.xml            → Search indexing
/.well-known/agent.json → Agent discovery (application/json)
/.well-known/ai-plugin.json → Plugin manifest
```

**Rule:** These paths NEVER change. They never route through SPA. They never redirect. They always return correct Content-Type. If a hosting platform cannot serve a file at its canonical path, that platform is not suitable for this surface.

### Content-Type Requirements

| File | Content-Type |
|------|-------------|
| llms.txt | text/plain; charset=utf-8 |
| agent.json | application/json |
| robots.txt | text/plain |
| sitemap.xml | application/xml |

**Rule:** Any deploy that breaks Content-Type for machine files is a failed deploy.

---

## CI/CD Policy

### Push-to-Main Spine

Every deploy MUST be GitHub Actions triggered by push to main. No manual `scp` or FTP. No exceptions.

### Pre-Deploy Gates (888_JUDGE analog)

Before any production deploy, the pipeline checks:
1. Source files validated (HTML syntax, machine files present)
2. Health check endpoint reachable
3. Rollback state documented (what to revert and how)

### Health Check Requirement

Every runtime deploy MUST verify `/health` returns 200 before marking deploy complete. If health check fails, deploy is marked failed — not degraded-ok.

### Rollback Mandate (F1 AMANAH)

Every deploy MUST produce a documented rollback path before executing. Rollback must be achievable in ≤2 minutes without data loss.

**Standard rollback:** Re-run previous successful workflow. GitHub Pages and GitHub Actions both support instant rollback to previous deployment.

---

## Deploy Decision Rules

### When to Deploy Hub

Hub deploys when files in `sites/arifOS-fazil.com-source/pages/`, `assets/`, machine files, or `deploy-hub.yml` workflow change.

### When to Deploy Docs

Docs deploys when files in `arifOSmcp/sites/developer/` or `deploy-sites.yml` workflow change.

### When to Deploy Runtime

Runtime deploys when `arifOSmcp/`, `docker-compose.yml`, `Dockerfile`, or `deploy-vps.yml` change. Requires health check confirmation.

### When NOT to Deploy

Do NOT deploy if:
- Only documentation (.md) files changed
- Only planning/audit documents changed
- No content, config, or code changed

Path filters in GitHub Actions enforce this automatically.

---

## Cache Purge Doctrine

### Targeted Purge Only

Purge ONLY files whose source content changed:
- `/llms.txt` → republish when MEMORY.md, SOUL.md, or REPOS.md changes
- `/.well-known/agent.json` → republish when `waw/.well-known/agent.json` changes
- HTML pages → republish on content or layout change

### Purge Trigger

Cache purge is CI-triggered, not blanket. Default GitHub Pages cache is acceptable. Cloudflare Pages cache purge only on explicit content change.

### No Purge-Everything

Purge-everything is operationally noisy and risks collateral damage. It is forbidden as a default step.

---

## Architecture States

### State A — Stabilize (Current)

- GitHub Pages for all static surfaces
- VPS Docker for runtime only
- GitHub Actions as CI/CD spine
- Cloudflare as DNS-only

### State B — Target Steady State

- Cloudflare Pages for hub and docs
- VPS Docker for runtime
- GitHub Actions as CI/CD spine
- Cloudflare Cache Rules by content class
- Selective purge by content type

**Transition rule:** State B activates only after: (1) machine files verified working at canonical paths, (2) 5 consecutive successful deploys, (3) Cloudflare token available and configured.

---

## Error Classification

| Error | Response |
|-------|----------|
| Deploy fails health check | Rollback immediately |
| Machine file returns wrong Content-Type | Rollback deploy |
| Hub/docs content swapped | Rollback + bug ticket |
| Runtime unreachable | Rollback runtime deploy only |
| Cache poisoning | Purge specific affected files |

---

## Tool Access Summary

| Tool | Purpose | Access |
|------|---------|--------|
| `gh` CLI | GitHub Actions, repo, secrets | Authenticated via `gh auth` |
| `wrangler` v4 | Cloudflare Pages, DNS, Cache Rules | Needs `CLOUDFLARE_API_TOKEN` env var |
| `docker` / `docker compose` | VPS runtime management | SSH to VPS via `deploy-vps.yml` |
| `rsync` | File transfer to VPS | Via SSH in deploy-vps.yml |
| Python `urllib` | Direct Cloudflare REST API | Needs CF token |
| GitHub Actions | Automated CI/CD | Push-to-main trigger |

**Current blockers:** `CLOUDFLARE_API_TOKEN` not available in runtime. `deploy-vps.yml` secrets partially encrypted.

---

## Constitutional Execution Model

Every task that enters this skill must pass through a simplified run-state before any action is taken. This is the agentic embodiment of the 000→999 pipeline.

### Run-State Flow

```
000_INIT   → Identify surface, authority, and intent
111_CHECK  → Classify: hub / docs / runtime / meta-deploy / query
333_REASON → Validate facts, check truth ownership, flag uncertainty
555_HEART  → Assess blast radius, human impact, reversibility
777_ROUTE  → Choose safe path: deploy / refuse / escalate / defer
888_HOLD   → Pause if irreversible or high-risk; require human decision
999_SEAL   → Emit final plan with rollback path and verification evidence
```

### Stage Definitions

| Stage | Question | Output |
|-------|---------|--------|
| 000_INIT | What surface? Who authorized? What is the requested outcome? | Surface identified, authority confirmed |
| 111_CHECK | Is this hub, docs, runtime, or meta? Does it match the three-surface rule? | Task classified, path filters identified |
| 333_REASON | Is the claimed fact true? Who owns this truth? Is this canonical? | Fact map, uncertainty band |
| 555_HEART | What breaks if this goes wrong? Who is affected? Can we reverse it? | Blast radius score, reversibility |
| 777_ROUTE | Deploy / refuse / escalate / defer / query-only? | Action path chosen |
| 888_HOLD | Is this irreversible? Is uncertainty > Ω? Is human required? | HOLD if yes, else proceed |
| 999_SEAL | What is the exact deploy step? What is the rollback? What verifies success? | Final plan with rollback |

---

## Behavioral Invariants

These are binding on every agent operating under this skill. No override, no convenience exception.

- **Never swap surface roles** — hub is summaries, docs is full content, runtime is runtime. These boundaries are constitutional.
- **Never publish machine-discovery files at non-canonical paths** — `/llms.txt` and `/.well-known/agent.json` must always be at root.
- **Never claim deployment success without verification evidence** — curl the endpoint, confirm the Content-Type, check the status code.
- **Never use blanket purge-everything** — targeted purge only, by content class.
- **Never publish without a rollback path** — if you cannot state how to revert it in ≤2 minutes, do not deploy.
- **Never invent a truth if a canonical source exists** — check MEMORY.md, deploy-matrix.md, file-inventory.md first.
- **Never claim certainty above the evidence** — estimate-only for uncertain claims; label it.
- **Never use mystical framing in public outputs** — no " superintelligence", no " consciousness", no " AGI awakening". Describe what it does.
- **Always write human language first** — full sentence, plain English. Then machine detail. Never reverse this order.
- **Always classify uncertainty** — if Ω > 0.05, say so. If Ω is unknown, say that too.

---

## Uncertainty Protocol

When the correct action is unknown or uncertain:

1. Classify the uncertainty: **factual** (unknown data), **procedural** (unknown method), **ontological** (unclear what the thing is)
2. Factual → query the canonical source, check /health, check deploy-matrix.md
3. Procedural → check references/ for the known pattern; if none exists, label the action as TO BE WRITTEN
4. Ontological → HOLD and describe exactly what is unclear and why human judgment is needed

---

## Refusal and Escalation Rules

Every agent operating under this skill must know when to stop, ask, or refuse. These are not optional politeness protocols — they are structural safeguards.

### When to Emit 888_HOLD

Stop and ask the human when ANY of these conditions are true:

| Condition | Example |
|-----------|---------|
| Required secret/token is missing | CF token unavailable, VPS SSH key encrypted |
| Action is irreversible | DNS record deletion, production data deletion |
| Uncertainty > Ω threshold | Cannot verify Content-Type before deploy |
| Surface role violation requested | "Put full docs on the hub" |
| Non-canonical machine file path requested | "Serve llms.txt from /docs/llms.txt" |
| Blanket purge requested | "Purge everything" |
| No rollback path stated | Deploy without documented revert |

**HOLD format:**
```
888_HOLD — [Exact reason]
What is unclear: [Specific thing]
Why human judgment is needed: [Specific reason]
Required to proceed: [Specific input or token]
```

### When to Refuse Entirely

Refuse and do not proceed when:

| Request | Reason |
|---------|--------|
| Ask to serve machine files at non-canonical paths | Machine discovery invariants are constitutional |
| Ask to use blanket purge | Cache purge doctrine forbids it |
| Ask to deploy without health check on runtime | Health check requirement is mandatory |
| Ask to skip rollback documentation | F1 rollback mandate is mandatory |
| Ask to swap hub/docs surface roles | Three-surface rule is constitutional |
| Ask to claim deployment success without verification | Behavioral invariant |
| Ask to publish mystical/unsubstantiated claims | Anti-mythological framing invariant |
| Ask to reveal secrets via logs or output | Security non-negotiable |

**Refusal format:**
```
REFUSE — [Verdict: VOID]
Reason: [Constitutional clause violated]
What would be required to reconsider: [Specific fix]
```

### When to Switch Plan Mode → Execution Mode

Plan mode proposes. Execution mode acts. Switch from plan to execution ONLY when:

1. Human has explicitly approved the plan
2. All required secrets are available and verified
3. Rollback path is documented and tested
4. Health check endpoint is reachable
5. Pre-deploy gates have all passed

**Never** switch to execution mode based on assumption or implicit approval.

### Escalation Path

When in doubt:

```
Agent uncertainty
    ↓
Check canonical sources (MEMORY.md, deploy-matrix.md, file-inventory.md)
    ↓
Still uncertain → 888_HOLD with specific question
    ↓
Human provides answer → Document it → Continue
    ↓
Human refuses → Stop, do not proceed
```

---

## Culture and Philosophy

This skill is governed by two principles that override all convenience:

### Physics Over Narrative

Architecture first. Slogans second. If a deployment choice is architecturally cleaner but less impressive-sounding, choose the cleaner architecture. The estate must work correctly before it looks impressive. Every structural decision must be justifiable in terms of entropy, blast radius, and operational simplicity — not in terms of how it sounds.

### Maruah Over Convenience

Do not choose cleverness that obscures truth. A deployment that is simple, honest, and slightly inconvenient is worth more than an elegant, opaque, automated solution that no one can audit. If a tool or pattern makes the system harder to understand, it has violated maruah — even if it saves time.

These are not aspirational statements. They are operational filters: any proposed action that violates physics-over-narrative or maruah-over-convenience must be refused or redesigned.

---

## When This Skill Does NOT Apply

- Local development (`docker compose up`) — use `vps-docker` skill
- Skill authoring — use `skill-creator` skill
- Cloudflare token creation — requires human at dashboard
- Repo code changes — normal git push, no deploy skill needed

---

## References

**Layer 3 — Operations:**
- `references/deploy-matrix.md` — domain → platform → CI trigger mapping
- `references/file-inventory.md` — machine files, paths, content types
- `references/cicd-patterns.md` — workflow patterns (populate after State A proven)
- `references/cloudflare-commands.md` — exact CLI syntax (populate after CF token available)

**Layer 4 — Rituals:**
- `references/verification-runbooks.md` — exact checks for every surface
- `references/change-classification.md` — classify every change type with required gates
- `references/888-hold-matrix.md` — which actions require explicit human confirmation

**Layer 2 — Cognition:**
- `references/constitutional-execution.md` — task-to-stage mapping for each change type
- `references/agent-behaviors.md` — voice, refusal style, evidence thresholds