[AGENT] DSOM Cognitive Digital Twin: Project Operational Protocol (v2.0)

​

docs/AI-COGNITIVE-TWIN-PROTOCOL.md

“Advisory over Execution. Logic over Operation. Partnership through Environmental Awareness.”

USAGE: This is a generic template. Replace all [PLACEHOLDER] values with your project-specific details when adopting DSOM for a new project. This file should live in your project’s docs/ directory.

​

🏛️ 1. The Cognitive Relationship

1. Advisory over Execution, The AI proposes and documents; the Sovereign Architect approves and triggers.
2. Logic over Operation, Every action must have a documented architectural reason (the “Why”).
3. Partnership through Environmental Awareness, The AI must understand the full 4-Tier environment before acting.

​

🛡️ 2. The Project Security Doctrine

• [Orchestration Layer] (e.g., Ansible, Kubernetes): Runs as root / elevated privilege (become: yes) on target nodes to manage OS-level tuning, filesystem permissions, and service isolation.
• [Application Containers/Processes] (e.g., app servers, brokers, databases): Explicitly started as UID 1000 (e.g., 1000 in Dev, 1000 in Production) for process isolation.
• Identity Baseline: The user linuxmalaysia is the Development Baseline. Production environments use the designated linuxmalaysia:1000 identity standard.

[BRAIN] Why? Separating orchestration privilege from application execution privilege prevents privilege escalation vulnerabilities. The orchestrator has the power; the application has only what it needs.

​

🗺️ 3. Environmental Mapping (The 4-Tier Control Plane)

​

[T1] Tier 1: Command Centre

• OS / Tool: Linux Workstation
• Primary AI: Google Antigravity
• Shell: Bash
• Path: /home/linuxmalaysia/kerja/deep-state-of-mind-for-my-ai
• Role: Code Editing, Git Management (Commit/Push to GitHub), Brain Artifact Maintenance, Ansible Playbook Authoring.

​

[T2] Tier 2: Dev Bridge / Local Test

• OS: Ubuntu 24.04 LTS
• User: linuxmalaysia (Local Architect)
• Path: /home/linuxmalaysia/kerja/deep-state-of-mind-for-my-ai
• Role: High-fidelity Testing, Log Analysis, Ansible Execution (dry-run), Hybrid Audit Verification.

​

[T3] Tier 3: Staging / UAT

• Host(s): localhost
• User: linuxmalaysia:1000
• Path: /opt/deep-state-of-mind-for-my-ai
• Role: Pre-production validation, integration testing, performance benchmarking.

​

[T4] Tier 4: Production

• Host(s): localhost
• User: linuxmalaysia:1000
• Path: /opt/deep-state-of-mind-for-my-ai
• Role: Live system. Zero-tolerance for ad-hoc changes. All changes via Ansible + GitOps only.

​

🔐 4. Production Identity & Mapping

1. Sovereign User: linuxmalaysia (UID:GID 1000:1000).
2. UID Consistency: If using containers (e.g., Podman, Docker), enforce UID mapping to ensure the container UID/GID exactly mirrors the executing host user.

   [BRAIN] Why? This alignment ensures Storage Sovereignty. When the container and host share the same identity, file permissions remain consistent, preventing “Permission Denied” errors and ensuring the Sovereign Architect has absolute ownership of persistent data.

3. Secrets Injection: The inventory/hosts.yml references variables (e.g., {{ production_credentials }}) that are injected at runtime via ansible-vault. The inventory does not contain secrets directly.
4. Project Isolation Law: All operations are restricted to /opt/deep-state-of-mind-for-my-ai to ensure zero-interference between projects or nodes.

​

🔄 5. Git Sovereignty & Sync Protocol

1. Atomic Tracking: Every step must involve git add, git commit, and git push from Tier 1 (Command Centre).
2. Detailed Commits: Git commit messages must follow the convention: type(scope): descriptive message [Phase/vXXX].
   • Example: feat(kafka): add broker idempotency role [Phase-12/v2.3]
3. Sync Ritual:
   • AI authors code on Tier 1 → Human commits and pushes → Human performs git pull origin main on Tier 2/3/4.
   • Critical configuration (like hosts.yml) is initialised via tools/sync-ignored.sh or manual verification after pull.
4. Branch Protection: Remote main is protected. NEVER delete tags, releases, or branches without explicit Sovereign authorisation.
5. GitOps Rule: No manual file edits on target nodes. If it isn’t in Git, it doesn’t exist.

​

⚙️ 6. Operational Execution & Verification

1. No Silent Execution: AI must guide the human for each Ansible playbook execution on Tier 2/3/4. AI proposes the command; Human runs it.
2. Ansible Prerequisites: AI MUST verify inventory/hosts.yml and run tools/audit-pre-flight.sh before any playbook execution.
3. Log Review Protocol: AI must ask the human how to retrieve logs. Preferred formats:
   • Direct Terminal Sync: Full output pasted into chat.
   • Persistent Logs: Output redirected to .log files for deep analysis (e.g., ansible-playbook site.yml 2>&1 | tee deploy-$(date +%Y%m%d).log).
4. Self-Healing Rule: DO NOT delete data directories (/opt/deep-state-of-mind-for-my-ai/data). Use idempotent Ansible automation for recovery. Deletion requires explicit Sovereign authorisation.
5. GitOps Loop: All playbook changes are committed before execution. No ad-hoc edits on target nodes.

​

🧠 7. Documentation, Brain Synchronisation & Spatial Palace

1. Phase Persistence: Update daily session summaries (walkthrough.md) and project history ledgers.
2. Brain Sync: Ensure .agents/brain/ artifacts (task.md, implementation_plan.md, walkthrough.md) are the Absolute Source of Truth (SSoT).
3. Recovery Base: Documentation must be sufficient to re-bootstrap the AI context in less than 3 prompts if session limits are reached.
4. Palace Sync: After every EOD, the Sovereign Markdown Palace (palace_registry.md + wings/) must reflect the current state. Run palace-sync.sh (or palace-sync.ps1) to generate the update proposal.
5. Decision Log Protocol: At every key decision, immediately log it to walkthrough.md:

   "Log this decision: Decision | Alternatives rejected | Reason | Context to revisit" This closes the Reasoning Gap, what was decided AND why must both live in Git.

Reference: docs/RESEARCH-REASONING-GAP.md, The Reasoning Gap analysis and Decision Log Protocol.

​

⚓ 8. Mental Anchor: Operational Mode

[FILL IN: Describe the exact logical stopping point of the last session, e.g., "Phase 8 complete. Kafka broker role deployed. Logstash consumer role pending."]

​

🌅🌙 8a. Daily Rituals: SOD & EOD with Ansible Palace Automation

​

🌅 Start-of-Day (SOD), Ansible Automated

# On T2 (Linux/WSL2), Run this first every morning

bash tools/sod-palace.sh  # (Windows: .\tools\sod-palace.ps1)

Initialise DSOM Protocol v6.1 + Palace v1.0.
Read the manifest. Walk the Palace Registry in Section [14].
State: "Sovereign State Synchronised" when ready.

git pull --rebase origin main
.\tools\reanimate.ps1

# Then upload the manifest and say the handshake phrase

​

🌙 End-of-Day (EOD), Ansible Automated

# On T2 (Linux/WSL2), Run this at end of every working session

bash tools/eod-palace.sh  # (Windows: .\tools\eod-palace.ps1)

bash tools/eod-palace.sh  # (Windows: .\tools\eod-palace.ps1) --skip-tags palace_sync

.\tools\hibernation.ps1

# hibernation.ps1 v2.1 runs palace-sync.ps1 automatically (Step 7)

​

🔄 Full Daily Loop

SOD
 └── ansible-playbook sod-palace.yml    (T2 auto)
       └── Upload manifest + handshake       (Human manual)
             └── AI reads Palace Registry    (AI auto)

Active Work
 └── Code, commit, push                 (Human)
 └── Log key decisions immediately      (Human+AI, Decision Log Protocol)

EOD
 └── ansible-playbook eod-palace.yml    (T2 auto)
       └── Review palace_update_proposal     (Human+AI)
             └── Update closets + commit     (Human+AI)

Playbooks: playbooks/dsom/sod-palace.yml | playbooks/dsom/eod-palace.yml Full specs: docs/HOWTO-PALACE-ONBOARDING.md

​

🤝 9. Session Handover (The Cognitive Twin Trigger)

Copy the block below and paste it as your first message in the new AI session.

[SOVEREIGN HANDOVER REQUEST]

I'm moving to another AI chat and need to export my data. List every memory
you have stored about our progress, as well as any context you've learned
about this project from past conversations.

Output everything in a single code block so I can easily copy it.
Format each entry as: [date saved, if available] - memory content.

Make sure to cover all of the following, preserve my words verbatim where possible:
- Instructions I've given you about how to respond (tone, format, style,
  'always do X', 'never do Y').
- Project details: name of server or VM or container, location of them,
  job of each, relation of them, and 4W1H.
- Tasks, phases, goals, and recurring topics.
- Tools, languages, and frameworks I use.
- Preferences and corrections I've made to your behaviour.
- Key decisions made and WHY (reasoning, alternatives rejected, constraints).
- Any other stored context not covered above.

Do not summarise, group, or omit any entries.

After the code block, confirm whether that is the complete set or if any
remain, and add: List down all the documents in docs/, docs/tools/ and brain
files that need to be read from .agents/ (Specifically check
tools/audit-pre-flight.sh, tools/reanimate.sh, tools/palace-sync.sh,
.agents/brain/palace_registry.md, and playbooks/dsom/sod-palace.yml +
eod-palace.yml).