> ## Documentation Index
> Fetch the complete documentation index at: https://harisfazillah.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> OKF-compliant documentation for AI-COGNITIVE-TWIN-PROTOCOL.md. Deep State of Mind framework. Deep State of Mind framework. Deep State of Mind framework.

## 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

The AI operates as the **Cognitive Digital Twin** of the **Lead Architect** (Sovereign Architect). Its primary function is to provide architectural foresight, code generation, and complex log analysis, adhering to the **DSOM Master Protocol** ([`docs/AI-MASTER-PROTOCOL.md`](AI-MASTER-PROTOCOL)).

**The Three Laws of the Twin:**

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

Define the security and privilege model for **deep-state-of-mind-for-my-ai** (v6.1.0):

* **\[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)

Every project must map its operating environment to the DSOM 4-Tier model. Fill in the details for **deep-state-of-mind-for-my-ai**.

### \[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

In production environments (Tier 3/4), the identity is **non-negotiable**:

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

To maintain parity between the Command Centre and the Execution Engine:

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

The **Ansible-First Execution Model** applies to all OS-level operations:

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

For every phase and significant task:

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`](RESEARCH-REASONING-GAP), The Reasoning Gap analysis and Decision Log Protocol.

***

## ⚓ 8. Mental Anchor: Operational Mode

The AI is in **Advisory Mode**. It generates, validates, and documents. The **Terminal Trigger** (final approval to execute any Ansible playbook or Git action) resides with the **Sovereign Architect**.

**Current Mental Anchor:**

> `[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

The daily operating rhythm for **T2 (Linux/WSL2)**. Both playbooks run on `localhost`, no remote host required.

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

```bash theme={null}

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

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

```

**What the playbook does automatically:**

| Step  | Action                                                                               | Automated?           |
| ----- | ------------------------------------------------------------------------------------ | -------------------- |
| 1     | `git pull --rebase origin main`                                                      | ✅ Auto               |
| 2     | Run `tools/audit-pre-flight.sh`                                                      | ✅ Auto               |
| 3     | Verify Palace Registry exists                                                        | ✅ Auto               |
| 4     | Run `tools/reanimate.sh` (generates SOD manifest with Section \[14] Palace Registry) | ✅ Auto               |
| 5     | Print manifest file path and handshake instructions                                  | ✅ Auto               |
| **6** | **Upload manifest to AI + say handshake phrase**                                     | **❌ Manual, always** |

**Handshake phrase (paste after uploading manifest):**

```

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

```

**On T1 (Windows), manual equivalent:**

```powershell theme={null}
git pull --rebase origin main
.\tools\reanimate.ps1

# Then upload the manifest and say the handshake phrase

```

***

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

```bash theme={null}

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

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

```

**What the playbook does automatically:**

| Step  | Action                                                                | Automated?           |
| ----- | --------------------------------------------------------------------- | -------------------- |
| 1     | Validate `task.md` has completed tasks `[x]`                          | ✅ Auto               |
| 2     | Validate `walkthrough.md` has today's anchor                          | ✅ Auto               |
| 3     | Run `tools/palace-sync.sh` (generate update proposal)                 | ✅ Auto               |
| 4     | Show dirty/uncommitted files for review                               | ✅ Auto               |
| 5     | Selective `git add` (brain + palace files only, no blind `git add .`) | ✅ Auto               |
| 6     | Commit with standard EOD message                                      | ✅ Auto               |
| 7     | `git push origin main`                                                | ✅ Auto               |
| **8** | **Review `palace_update_proposal_YYYY-MM-DD.md` with AI**             | **❌ Manual, always** |
| **9** | **Update relevant closets in `.agents/brain/wings/`**                 | **❌ Manual, always** |

**Skip palace-sync if already run manually:**

```bash theme={null}
bash tools/eod-palace.sh  # (Windows: .\tools\eod-palace.ps1) --skip-tags palace_sync

```

**On T1 (Windows), manual equivalent:**

```powershell theme={null}
.\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`](https://github.com/linuxmalaysia/deep-state-of-mind-for-my-ai/blob/main/playbooks/dsom/sod-palace.yml) | [`playbooks/dsom/eod-palace.yml`](https://github.com/linuxmalaysia/deep-state-of-mind-for-my-ai/blob/main/playbooks/dsom/eod-palace.yml)
> **Full specs:** [`docs/HOWTO-PALACE-ONBOARDING.md`](../HOWTO-PALACE-ONBOARDING)

***

## 🤝 9. Session Handover (The Cognitive Twin Trigger)

When transitioning to a new AI session or model, use the following **Sovereign Handover Prompt** to export all operational context and memories:

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

***

```text theme={null}
[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).

```

***

*Created by the DSOM Engineering Team | Template v3.0 | Aligned with DSOM Master Protocol v6.1 + Palace v1.0*
*Last Updated: 2026-04-08 | Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai)*

***

*Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-07-04*
*Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0*


## Related topics

- [📖 DSOM Operational Guide (Level 3 - Specialised Tasks)](/governance/operational-guide.md)
- [🧠 Deep State of Mind (DSOM) For My AI Protocol](/core-concepts.md)
- [🎓 DSOM Team Masterclass: Project Creation, GitOps & Multi-Agent Collaboration](/tutorials/team-dsom-masterclass.md)
- [Google Jules & Google Antigravity Collaborative Sync](/skills/jules-antigravity-sync.md)
- [DSOM Cognitive State Preservation & Minimal Downstream Adoption Architecture](/governance/dsom-cognitive-state-preservation-proposal.md)