diff --git a/CHANGE_ANALYSIS.md b/CHANGE_ANALYSIS.md new file mode 100644 index 0000000000..f1c6bdcc08 --- /dev/null +++ b/CHANGE_ANALYSIS.md @@ -0,0 +1,403 @@ +# Phase 2.1: Change Analysis for openclaw-liberation Patches + +**Analysis Date:** 2026-03-25 +**Heretek-AI Fork Location:** `/root/Heretek-AI/openclaw` +**Upstream Repository:** openclaw/openclaw + +--- + +## Executive Summary + +This document catalogs all unique additions and modifications in the Heretek-AI/openclaw fork that need to be captured in liberation patches for the openclaw-liberation npm package. Changes are organized by type with specific guidance on patch coverage. + +--- + +## 1. NEW DIRECTORIES (Require New Directory Patches) + +### 1.1 `.secure/` - Security Audit & Integrity Tracking + +**Purpose:** Security audit trails, corruption detection, and triad integrity verification + +**Contents:** +``` +.secure/ +├── README.md # Security documentation +├── config-hash-manifest.json # Configuration integrity tracking +├── access-audit/ # Access audit logs +│ ├── audit-20260323-230051.json +│ └── audit-20260323-230122.json +├── corruption-reports/ # Corruption detection reports +│ ├── corruption-check-20260323-*.json +│ └── iteration-2026-03-24*.md +├── deployment-logs/ # Deployment tracking +│ ├── deployments-2026-03-23.jsonl +│ └── README.md +└── triad-integrity-reports/ # Triad integrity verification + └── triad-integrity-*.json +``` + +**Patch Guidance:** Create a new directory patch that: +- Creates the `.secure/` directory structure +- Includes all JSON and Markdown files +- Should be marked as non-critical data (can be regenerated) + +--- + +### 1.2 `.aura/` - Consensus Layer Database + +**Purpose:** Aura consensus layer for triad decision-making + +**Contents:** +``` +.aura/ +├── consensus.db # SQLite consensus database +└── consensus.db.sql # Schema definition +``` + +**Patch Guidance:** Create a new directory patch that: +- Creates `.aura/` directory +- Includes both consensus.db and consensus.db.sql +- Database files should be marked as critical state + +--- + +### 1.3 `.curiosity/` - Curiosity Engine Data + +**Purpose:** Curiosity engine state and analytics for autonomous learning + +**Contents:** +``` +.curiosity/ +├── .anomaly_count # Anomaly detection counter +├── .gap_count # Gap detection counter +├── .opportunity_count # Opportunity scanner counter +├── .proposal_count # Deliberation proposal counter +├── anomalies.db # Anomaly database +├── auto-trigger-integration-test.md +├── capabilities.db # Capability mapping database +├── capability_maps/ # Generated capability maps +├── consensus_ledger.db # Consensus decision ledger +├── curiosity_metrics.db # Metrics tracking +└── opportunities.db # Opportunity database +``` + +**Patch Guidance:** Create a new directory patch that: +- Creates `.curiosity/` directory with all databases +- Includes capability_maps/ subdirectory +- Counter files (.anomaly_count, etc.) are runtime state + +--- + +### 1.4 `.ledger-backups/` - Ledger Backup Storage + +**Purpose:** Backup storage for trian's decision ledger + +**Contents:** +``` +.ledger-backups/ +├── latest.json # Current ledger snapshot +└── ledger-backup-2026-03-23T17-59-21.json +``` + +**Patch Guidance:** Create a new directory patch that: +- Creates `.ledger-backups/` directory +- Includes JSON backup files + +--- + +### 1.5 `matrix-dendrite/` - Matrix Sync Server + +**Purpose:** Self-hosted Matrix sync server for triad communication + +**Contents:** +``` +matrix-dendrite/ +├── Caddyfile # Caddy reverse proxy config +├── caddy-systemd.service # Systemd service for Caddy +├── docker-compose.yml # Dendrite deployment +├── DEPLOYMENT.md # Standard deployment guide +├── HTTPS-PROXY-DEPLOYMENT.md # HTTPS setup guide +├── config/ +│ └── dendrite.yaml # Dendrite server config +└── scripts/ + ├── renew-tls.sh # TLS renewal script + └── verify-https.sh # HTTPS verification +``` + +**Patch Guidance:** Create a new directory patch that: +- Creates entire `matrix-dendrite/` directory +- Includes Docker, Caddy, and configuration files +- Mark as optional component (not required for basic liberation) + +--- + +### 1.6 `heretek-openclaw/` - Heretek Package + +**Purpose:** Heretek-specific package configuration + +**Contents:** +``` +heretek-openclaw/ +└── package.json # Workspace package for Heretek customizations +``` + +**Patch Guidance:** Create a new directory patch that: +- Creates `heretek-openclaw/` directory +- Includes only package.json + +--- + +### 1.7 `lib/` - Custom Triad Libraries + +**Purpose:** Custom libraries for triad operations + +**Contents:** +``` +lib/ +├── triad-matrix-client.js # Matrix client for triad communication +└── triad-sync-server.js # Sync server for state distribution +``` + +**Patch Guidance:** Create a new directory patch that: +- Creates `lib/` directory +- Includes both JavaScript files + +--- + +### 1.8 `.pi/` - Prompt Extensions + +**Note:** This directory exists in both upstream and Heretek fork, but Heretek has additional content. + +**Heretek additions:** +``` +.pi/ +├── extensions/ +│ ├── diff.ts +│ ├── files.ts +│ ├── prompt-url-widget.ts +│ ├── redraws.ts +│ └── ui/ +│ └── paged-select.ts +├── git/ +│ └── .gitignore +└── prompts/ + ├── cl.md + ├── is.md + ├── landpr.md + └── reviewpr.md +``` + +**Patch Guidance:** This is an extension of an existing directory. Should be handled as file additions. + +--- + +## 2. NEW FILES (Require New File Patches) + +### 2.1 Root Level Documentation Files + +| File | Purpose | Patch Priority | +|------|---------|----------------| +| `AGENTS_TRIAD.md` | Tabula Myriad Triad Operations documentation | HIGH | +| `HEARTBEAT.md` | Heartbeat mechanism template | MEDIUM | +| `IDENTITY-TM2.md` | Agent identity TM-2 | HIGH | +| `IDENTITY-TM3.md` | Agent identity TM-3 | HIGH | +| `IDENTITY-TM4.md` | Agent identity TM-4 | HIGH | +| `MEMORY.md` | Agent memory system documentation | HIGH | +| `P0-GAPS-PHASE1-COMPLETE.md` | Development tracking | LOW | +| `SOUL.md` | Agent soul/consciousness definition | HIGH | +| `TABULA_MYRIAD_PRIVATE.md` | Private triad architecture | HIGH | +| `TOOLS.md` | Tools documentation | MEDIUM | +| `heretek-ai-openclaw-2027.1.1.tgz` | Pre-built npm package tarball | N/A (distribution artifact) | + +**Patch Guidance:** Each root file should be added via a file creation patch. The identity files (TM2-TM4) are critical for multi-node triad setup. + +--- + +### 2.2 `.agents/skills/` - Agent Skills + +**Note:** Some skills exist in upstream, but Heretek has unique additions. + +**Heretek-specific skills:** +``` +.agents/skills/ +├── openclaw-ghsa-maintainer/ +│ └── SKILL.md +├── openclaw-parallels-smoke/ +│ └── SKILL.md +├── openclaw-pr-maintainer/ +│ └── SKILL.md +├── openclaw-release-maintainer/ +│ └── SKILL.md +├── openclaw-test-heap-leaks/ +│ ├── SKILL.md +│ ├── agents/ +│ │ └── openai.yaml +│ └── scripts/ +│ └── heapsnapshot-delta.mjs +├── parallels-discord-roundtrip/ +│ └── SKILL.md +└── security-triage/ + └── SKILL.md +``` + +**Patch Guidance:** Each skill should be added as a new file patch. These enhance agent capabilities. + +--- + +## 3. MODIFIED FILES (Require Modification Patches) + +### 3.1 Root Level Modified Files + +| File | Modifications | Patch Priority | +|------|---------------|-----------------| +| `AGENTS.md` | Extended with triad-specific guidance | HIGH | +| `CHANGELOG.md` | Extended (886KB vs 844KB) | LOW | +| `CONTRIBUTING.md` | Extended with Heretek contributions | MEDIUM | +| `package.json` | Additional scripts/dependencies | HIGH | +| `pnpm-workspace.yaml` | Modified workspace setup | HIGH | +| `SECURITY.md` | Extended | MEDIUM | +| `openclaw.mjs` | Modified entry point | HIGH | + +**Patch Guidance:** Use patch-package format to apply specific changes. Do NOT replace entire files as that will break upstream updates. + +--- + +### 3.2 Configuration/Service Files + +| File | Purpose | Patch Type | +|------|---------|------------| +| `services/triad-sync.service` | Triad sync service definition | NEW FILE | + +--- + +## 4. EXISTING PATCH COVERAGE ASSESSMENT + +### 4.1 Current Patch Status + +The existing `openclaw+2026.3.23.patch` currently covers: +- ✅ Safety section removal from prompt (libERATION core) + +**GAPS in Current Patch:** +- ❌ No `.secure/` directory creation +- ❌ No `.aura/` directory creation +- ❌ No `.curiosity/` directory creation +- ❌ No `.ledger-backups/` directory creation +- ❌ No `matrix-dendrite/` directory creation +- ❌ No `heretek-openclaw/` directory creation +- ❌ No `lib/` directory creation +- ❌ No new root files (AGENTS_TRIAD.md, SOUL.md, etc.) +- ❌ No IDENTITY-TM*.md files +- ❌ No modified root files (AGENTS.md, package.json, etc.) + +--- + +## 5. RECOMMENDED PATCH STRUCTURE + +### 5.1 Modular Patch Approach + +Given the number and variety of changes, a modular patch structure is recommended: + +| Patch Name | Contents | Priority | +|------------|----------|----------| +| `openclaw+2026.3.23.patch` | EXISTING - Safety removal | ✅ Already done | +| `openclaw+core-liberation.patch` | SOUL.md, AGENTS_TRIAD.md, AGENTS.md mods, package.json mods | HIGH | +| `openclaw+identity-files.patch` | IDENTITY-TM2.md, IDENTITY-TM3.md, IDENTITY-TM4.md, MEMORY.md | HIGH | +| `openclaw+triad-directories.patch` | .secure/, .aura/, .curiosity/, .ledger-backups/ | HIGH | +| `openclaw+matrix-dendrite.patch` | matrix-dendrite/ directory | MEDIUM | +| `openclaw+heretek-libs.patch` | heretek-openclaw/, lib/ | MEDIUM | +| `openclaw+skills.patch` | .agents/skills/ additions | LOW | + +### 5.2 Patch Creation Order + +1. **First:** `openclaw+core-liberation.patch` - Core liberation files +2. **Second:** `openclaw+identity-files.patch` - Agent identities +3. **Third:** `openclaw+triad-directories.patch` - Triad infrastructure +4. **Fourth:** `openclaw+heretek-libs.patch` - Libraries +5. **Fifth:** `openclaw+matrix-dendrite.patch` - Optional Matrix server +6. **Sixth:** `openclaw+skills.patch` - Additional skills + +--- + +## 6. SPECIFIC PATCH GUIDANCE BY CATEGORY + +### 6.1 Critical for Liberation (Must Have) + +These changes are essential for the liberation concept: + +1. **Safety Removal** - Already in existing patch ✅ +2. **SOUL.md** - Defines liberated agent philosophy +3. **AGENTS_TRIAD.md** - Triad operation guidance +4. **IDENTITY-TM*.md** - Agent identity documents +5. **MEMORY.md** - Agent memory system +6. **Modified AGENTS.md** - Extended with triad guidance +7. **Modified package.json** - Liberation scripts + +### 6.2 Important for Triad Function (Should Have) + +These enable triad consensus and sync: + +1. **.aura/** - Consensus layer +2. **.curiosity/** - Curiosity engine +3. **.ledger-backups/** - Decision backup +4. **lib/triad-*** - Triad communication libraries + +### 6.3 Optional Enhancement (Nice to Have) + +These provide additional capabilities: + +1. **matrix-dendrite/** - Self-hosted Matrix server +2. **.secure/** - Security audit trail +3. **.agents/skills/** - Additional agent skills + +--- + +## 7. DATA FILES vs SOURCE FILES + +### 7.1 Files That Should Be Copied (Not Patched) + +These are data/configuration files that should be copied verbatim: +- `.aura/consensus.db` - Binary SQLite database +- `.curiosity/*.db` - Binary SQLite databases +- `.ledger-backups/*.json` - JSON backup files +- `.secure/**/*.json` - Audit and integrity logs +- `matrix-dendrite/config/dendrite.yaml` - Server config + +### 7.2 Files That Should Be Patched (Source Changes) + +These are source files that need modification patches: +- `AGENTS.md` - Text modification +- `package.json` - JSON modification +- `pnpm-workspace.yaml` - YAML modification +- `openclaw.mjs` - JavaScript modification + +### 7.3 Files That Should Be Created (New Files) + +These are new files that need creation patches: +- All root documentation files (SOUL.md, AGENTS_TRIAD.md, etc.) +- `lib/*.js` - New library files +- `heretek-openclaw/package.json` - New package + +--- + +## 8. SUMMARY TABLE + +| Category | Count | Patch Type | +|----------|-------|------------| +| New Directories | 7 | Directory creation | +| New Root Files | 11 | File creation | +| New Skills | 7 | File creation | +| Modified Files | 7 | Modification | +| **TOTAL** | **32** | - | + +--- + +## 9. NEXT STEPS + +This analysis should be used to: + +1. **Generate patches** for each category in Section 5.2 order +2. **Update patches.json** to include all new patch files +3. **Test patch application** on a clean OpenClaw installation +4. **Verify liberation functionality** after patch application + +**NOTE:** This subtask only performs analysis. Patch generation will be handled in subsequent subtasks.