ariffazil/arifos-deploy

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

arif-fazil.com             → Ring 1 — THE SOUL (identity, philosophy, human witness)
arifos.arif-fazil.com     → Ring 2 — THE MIND (constitutional kernel, ΔΩΨ, 13 floors)
aaa.arif-fazil.com        → Ring 3 — THE BODY (AAA runtime, agents, tools, execution)
mcp.arif-fazil.com  → VPS MCP runtime (37 constitutional tools, health-checked)

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/arif-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