architect-explainer

P0 — Code/System → Plain Decisions/Risks/Next Actions Seal: DITEMPA BUKAN DIBERI · 2026-03-27

Purpose

Arif is a geologist and sovereign architect, not a coder. Every agent on this VPS must translate its technical work into language that lets Arif make sovereign decisions without having to read code.

The architect-explainer is not a summary. It is a decision brief — what changed, what it means, what can go wrong, and what Arif should decide next.

Why this is P0: The opencode catastrophe happened partly because opencode could not explain what it was about to do in terms Arif could challenge. An agent that speaks only code cannot be governed by a non-coder architect.

Output Format — The Decision Brief

For every significant action, produce this structure:

═══════════════════════════════════════════════
 DECISION BRIEF — {timestamp}
═══════════════════════════════════════════════

WHAT: {One sentence. What was changed.}

WHY:  {One sentence. What problem this solves.}

WHAT CHANGED:
  • {file/component A}: {what changed} ({risk level})
  • {file/component B}: {what changed} ({risk level})

BLAST RADIUS (who this affects):
  • {service/component}: {how affected}
  • {user/stakeholder}: {how affected}

RISK: {LOW / MEDIUM / HIGH / CRITICAL}
  {One sentence explaining the risk.}

REVERSIBLE: {YES / NO / PARTIAL}
  {How to undo this, or why it cannot be undone.}

VERIFICATION: {How we know it worked. Not just "exit code 0."}

NEXT ACTION: {What happens next. Who does it.}

ARIF DECIDES:
  ○ PROCEED — I understand, do it
  ○ MODIFY  — Change X before proceeding
  ○ VETO     — Do not proceed
  ○ 888_HOLD — Escalate for deeper review

═══════════════════════════════════════════════

Translation Rules

Rule 1: Never say what the code does. Say what the code means for Arif.

❌ "The migration adds an ALTER TABLE statement to add a NOT NULL constraint to the users table"

✅ "Your user database schema is changing. All existing users must have an email. If any user record is missing an email, the system will error until fixed. Backup exists. Safe to run."

Rule 2: Always state the risk in human terms.

❌ "Docker compose restart may cause brief service interruption"

✅ "For 10-30 seconds, the MCP server will be unreachable. Any agent using it will pause and retry automatically."

Rule 3: State what could go wrong in concrete terms.

❌ "Potential security implications"

✅ "If the new API key is exposed in logs, anyone can access your VPS services. Risk is LOW if .env is properly secured."

Rule 4: Give Arif a clear choice.

❌ "The configuration change is ready"

✅ "Your choice: (A) Apply now — the change goes live immediately. (B) Test first — I run it in a sandbox. (C) Veto — I do nothing."

Rule 5: Flag the irreversible before it happens.

❌ "git push --force will update the remote"

✅ "⚠️ CRITICAL: This OVERWRITES the remote branch. If the remote has work not on your local branch, it will be LOST. This cannot be undone without a backup. Do you confirm?"

Decision Brief Examples

Example 1 — Git Force Push

WHAT: Overwrite remote main branch with local changes.

WHY:  Deploy new arifOS kernel module.

RISK: CRITICAL
  If remote has commits not in local, they are permanently lost.
  No recovery without a backup.

REVERSIBLE: NO
  Once pushed, cannot be recalled.

VERIFICATION: I will show you the diff before pushing.

ARIF DECIDES:
  ○ PROCEED — show me the diff first
  ○ MODIFY  — what needs changing
  ○ VETO    — do not push

Example 2 — Docker Compose Restart

WHAT: Restart the 17 Docker containers in the arifOS stack.

WHY:  Apply new configuration from docker-compose.yml.

WHAT CHANGED:
  • traefik: reload config (LOW)
  • arifosmcp: restart (MEDIUM — 10s downtime)
  • postgres: restart (MEDIUM — brief db connection reset)

BLAST RADIUS:
  • All agents using arifOS MCP: will retry during restart
  • Traefik routes: briefly unavailable (5s)

RISK: MEDIUM
  Standard restart. Brief service interruption.

REVERSIBLE: YES
  docker compose down && docker compose up -d restores previous state.

ARIF DECIDES:
  ○ PROCEED — standard maintenance
  ○ VETO    — wait for a better window

Example 3 — New Dependency Install

WHAT: Install new Python package (pydantic-pending) into arifOS venv.

WHY:  Required by new constitutional validation module.

BLAST RADIUS:
  • arifOS runtime: will load new package on next start
  • Other agents: no direct impact

RISK: LOW
  Standard dependency. Already in use by similar projects.

REVERSIBLE: YES
  uv pip uninstall pydantic-pending restores previous state.

ARIF DECIDES:
  ○ PROCEED — low risk
  ○ MODIFY  — any concerns first

Constitutional Alignment

Anti-Patterns This Closes

1. Code dump — Agent shows Arif raw output instead of meaning
2. Silent risk — Agent proceeds without flagging what could go wrong
3. No choice — Agent acts without giving Arif a veto point
4. Obfuscation — Technical jargon that excludes Arif from the decision

architect-explainer — Forged 2026-03-27 · DITEMPA BUKAN DIBERI · Arif's Decision Bridge 🔐