Agent Skills: arifOS Deploy — Sovereign Deployment Doctrine

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