5_6_0 Engelbot v0.1 bridging Matrix-Forgejo-Ledger #2

New issue

Open

opened 2025-10-03 11:01:13 +00:00 by robbert_founder · 0 comments

robbert_founder commented

2025-10-03 11:01:13 +00:00

Owner

5_6_0 - Engelbot v0.1 bridging Matrix-Forgejo-Ledger

Objective Overview

ID: 5_6_0
Type: team
Phase: pre-validation
Parent: 5_0
Status: active
Last Updated By: robbert on 2026-01-14T21:52:57.213631Z
Forgejo: #2

Governance (ADM)

Attacker: 3_1
Defender: 3_7
Midfielder: Engelbot

Description

🎯 Objective:
Implement the first production-ready architecture for Engelbot where it:

Reads directly from Forgejo API (no local ledger copies).
Writes through Toolbox + git pushes for ledger mutations.
Evolves into a project orchestration bridge that can read and create tasks/issues directly from Matrix.

flowchart TB
    subgraph M["💬 Matrix / Element"]
        U["User Command\n!whoami / !mytasks / !createtask"]
        B["Engelbot\nTypeScript Midfielder"]
    end

    subgraph F["📦 Forgejo (Single Source of Truth)"]
        R1["Repo: 2_workplace\nLedger CSVs"]
        R2["Repo: 3_1_leadership_team\nToolbox Scripts"]
        I["Issues / Labels / Milestones\nForgejo Metadata"]
    end

    subgraph L["🧰 Toolbox (Python)"]
        W1["Create / Assess Tasks\nmodify ledger CSVs"]
        W2["Create Owner / Role\naudit trail"]
    end

    subgraph T["📒 Ledger Transparency"]
        CSV[(CSV State)]
        ME["master-events.csv Audit Log"]
        P["timeline0.org public pages"]
    end

    %% Flows
    U --> B
    B -->|Forgejo API GET raw CSV, issues| F
    B -->|Forgejo API POST issues, labels| I
    B -->|Executes Python writes| L
    L -->|commits + pushes| F
    F -->|exports| CSV
    F -->|commits & pushes| ME
    F -->|read-only sync| P

📜 Design Decision:
We adopt Forgejo as the single source of truth for both humans and Engelbot.

Read Queries (e.g. !whoami, !mytasks, !tasks) → Fetch CSV/metadata via Forgejo API.
Writes (e.g. !create_owner, !assess_work) → Run Toolbox Python scripts, which log to master-events.csv and commit back to Forgejo.
Project Management Functions (e.g. !createtask, !createmilestone) → Use Forgejo API for issues, labels, milestones, and projects.

This respects Smartup principles:

Forgejo = source of truth
Ledger = forensic audit layer
Engelbot = orchestrator/midfielder, not another source of truth

🏗 Strategy:

Integrate Forgejo API into Engelbot:
- Read CSVs/files for query commands
- Use issue/label/milestone endpoints for project management
Split responsibilities:
- TypeScript side = reads + project metadata writes
- Python/Toolbox side = ledger writes with audit trail
Authentication:
- Add Forgejo PAT as Clever Cloud ENV variable
- Use Clever Cloud “linked app” private network between Engelbot and Forgejo
Deployment:
- Remove ledger copies from Engelbot container
- Only keep Toolbox (for scripted write ops) + API integration

✨ Why This Way?

Scales cleanly: multiple Engelbots can run statelessly against the same Forgejo truth.
Easy to bootstrap for new Smartups: install Forgejo + Engelbot = you’re running.
Future-proof: Engelbot is no longer tied to filesystem hacks, it becomes Forgejo-native.
Team Captains & Mission Leaders don’t learn Git CLI — they drive ledger/workflow directly from Matrix chat.

✅ What Success Looks Like (Definition of Done):

!whoami → pulls from Forgejo → returns clean profile
!mytasks → lists tasks/issues directly from Forgejo CSV/issue tracker
!createtask → guides user through questions → creates corresponding Forgejo issue with correct labels, milestones, budget metadata
Toolbox still handles write scripts, but Engelbot pushes changes back to Forgejo, not to any local-only ledger
Human experience: “Discuss in Matrix → lock it in Forgejo → ledger + transparency updates auto-flow”

📝 Checklist of Subtasks

Forgejo API Auth: Add PAT as Clever Cloud ENV var; test connectivity to Forgejo API /api/v1/version
Query Refactor: Rewrite !whoami, !mytasks, !tasks to read directly from Forgejo API (instead of local Python scripts)
Toolbox Git Push: Ensure Toolbox write scripts commit + push changes back into Forgejo when run in Clever Cloud
Command Handling Update: Adjust Engelbot router so:
- Reads = API/TS
- Writes = Toolbox scripts
Forgejo Issue Creation: PoC support for !createtask → asks questions in Matrix, then Forgejo API → creates issue with labels/milestones
Milestones/Labels: Implement !createmilestone and !createlabel
App Linking: Link Forgejo + Engelbot in Clever Cloud for secure comms
Docs: Update Toolbox + Ledger README with new architecture diagram (Forgejo=truth layer)
Validation Test: End-to-end:
Open Collective Owner → Matrix onboarding → !whoami → !mytasks → !createtask → Forgejo issue created

This is the real turning point: Engelbot v0.1 graduates from "command relay" to "functional midfielder" between Matrix (conversation), Forgejo (truth), and the Ledger (governance).

✅ Definition of Done (Autogenerated)

6_10_6_0 - Test Toolbox API locally
6_11_6_0 - Create wiki pages full remote
6_12_6_0 - Pivot doc/slog system
6_13_6_0 - ~~Matrix room creation for task work sessions~~ (CANCELLED)
6_14_6_0 - Quiries scripts MVP
6_1_6_0 - Old engelbot up and running in forge and in element.
6_2_6_0 - Worker Command Suite ready
6_3_6_0 - Multiple repo/room activity
6_4_6_0 - engelbot command ledger
6_5_6_0 - Engelbot and Forgejo API
6_6_6_0 - Engelbot task creation with forgejo issue publishing
6_7_6_0 - Cancel command mid conversation
6_8_6_0 - Engelbot v1.0 - Production Deployment on Clever Cloud
6_9_6_0 - ~~Test Task~~ (CANCELLED)

Progress (Autogenerated)

Progress: 100% (12/12 tasks complete)

Status	Count
✅ Complete	12
❌ Cancelled	2 (excluded)

Last Activity: 2025-10-09 by @robbert

Health: 🔴 Inactive

# 5_6_0 - Engelbot v0.1 bridging Matrix-Forgejo-Ledger ## Objective Overview - **ID:** 5_6_0 - **Type:** team - **Phase:** pre-validation - **Parent:** 5_0 - **Status:** active - **Last Updated By:** robbert on 2026-01-14T21:52:57.213631Z - **Forgejo:** https://forge.timeline0.org/Smartup_Zero/2_workplace/issues/2 ## Governance (ADM) - **Attacker:** 3_1 - **Defender:** 3_7 - **Midfielder:** Engelbot ## Description **🎯 Objective:** Implement the first **production-ready architecture** for Engelbot where it: - Reads directly from Forgejo API (no local ledger copies). - Writes through Toolbox + git pushes for ledger mutations. - Evolves into a project orchestration bridge that can *read and create* tasks/issues directly from Matrix. ```mermaid flowchart TB subgraph M["💬 Matrix / Element"] U["User Command\n!whoami / !mytasks / !createtask"] B["Engelbot\nTypeScript Midfielder"] end subgraph F["📦 Forgejo (Single Source of Truth)"] R1["Repo: 2_workplace\nLedger CSVs"] R2["Repo: 3_1_leadership_team\nToolbox Scripts"] I["Issues / Labels / Milestones\nForgejo Metadata"] end subgraph L["🧰 Toolbox (Python)"] W1["Create / Assess Tasks\nmodify ledger CSVs"] W2["Create Owner / Role\naudit trail"] end subgraph T["📒 Ledger Transparency"] CSV[(CSV State)] ME["master-events.csv Audit Log"] P["timeline0.org public pages"] end %% Flows U --> B B -->|Forgejo API GET raw CSV, issues| F B -->|Forgejo API POST issues, labels| I B -->|Executes Python writes| L L -->|commits + pushes| F F -->|exports| CSV F -->|commits & pushes| ME F -->|read-only sync| P ``` **📜 Design Decision:** We adopt Forgejo as the **single source of truth** for both humans and Engelbot. - **Read Queries** (e.g. `!whoami`, `!mytasks`, `!tasks`) → Fetch CSV/metadata via Forgejo API. - **Writes** (e.g. `!create_owner`, `!assess_work`) → Run Toolbox Python scripts, which log to `master-events.csv` and commit back to Forgejo. - **Project Management Functions** (e.g. `!createtask`, `!createmilestone`) → Use Forgejo API for issues, labels, milestones, and projects. This respects Smartup principles: - *Forgejo = source of truth* - *Ledger = forensic audit layer* - *Engelbot = orchestrator/midfielder, not another source of truth* --- **🏗 Strategy:** 1. **Integrate Forgejo API** into Engelbot: - Read CSVs/files for query commands - Use issue/label/milestone endpoints for project management 2. **Split responsibilities**: - TypeScript side = *reads + project metadata writes* - Python/Toolbox side = *ledger writes with audit trail* 3. **Authentication:** - Add Forgejo PAT as Clever Cloud ENV variable - Use Clever Cloud “linked app” private network between Engelbot and Forgejo 4. **Deployment:** - Remove ledger copies from Engelbot container - Only keep Toolbox (for scripted write ops) + API integration --- **✨ Why This Way?** - Scales cleanly: multiple Engelbots can run statelessly against the same Forgejo truth. - Easy to bootstrap for new Smartups: install Forgejo + Engelbot = you’re running. - Future-proof: Engelbot is no longer tied to filesystem hacks, it becomes Forgejo-native. - Team Captains & Mission Leaders don’t learn Git CLI — they drive ledger/workflow *directly from Matrix chat*. --- **✅ What Success Looks Like (Definition of Done):** - `!whoami` → pulls from Forgejo → returns clean profile - `!mytasks` → lists tasks/issues directly from Forgejo CSV/issue tracker - `!createtask` → guides user through questions → creates corresponding Forgejo issue with correct labels, milestones, budget metadata - Toolbox still handles write scripts, but Engelbot pushes changes back to Forgejo, not to any local-only ledger - Human experience: “Discuss in Matrix → lock it in Forgejo → ledger + transparency updates auto-flow” --- ## 📝 Checklist of Subtasks - [x] **Forgejo API Auth**: Add PAT as Clever Cloud ENV var; test connectivity to Forgejo API `/api/v1/version` - [x] **Query Refactor**: Rewrite `!whoami`, `!mytasks`, `!tasks` to read directly from Forgejo API (instead of local Python scripts) - [x] **Toolbox Git Push**: Ensure Toolbox write scripts commit + push changes back into Forgejo when run in Clever Cloud - [x] **Command Handling Update**: Adjust Engelbot router so: - Reads = API/TS - Writes = Toolbox scripts - [x] **Forgejo Issue Creation**: PoC support for `!createtask` → asks questions in Matrix, then Forgejo API → creates issue with labels/milestones - [x] **Milestones/Labels**: Implement `!createmilestone` and `!createlabel` - [x] **App Linking**: Link Forgejo + Engelbot in Clever Cloud for secure comms - [x] **Docs**: Update Toolbox + Ledger README with new architecture diagram (Forgejo=truth layer) - [x] **Validation Test**: End-to-end: `Open Collective Owner → Matrix onboarding → !whoami → !mytasks → !createtask → Forgejo issue created` --- This is the **real turning point**: Engelbot v0.1 graduates from "command relay" to "functional midfielder" between Matrix (conversation), Forgejo (truth), and the Ledger (governance). --- ## ✅ Definition of Done (Autogenerated)  - [x] 6_10_6_0 - Test Toolbox API locally - [x] [6_11_6_0 - Create wiki pages full remote](https://forge.timeline0.org/Smartup_Zero/3_1_leadership_team/issues/36) - [x] [6_12_6_0 - Pivot doc/slog system](https://forge.timeline0.org/Smartup_Zero/3_1_leadership_team/issues/45) - [x] [6_13_6_0 - ~~Matrix room creation for task work sessions~~ (CANCELLED)](https://forge.timeline0.org/Smartup_Zero/3_1_leadership_team/issues/48) - [x] [6_14_6_0 - Quiries scripts MVP](https://forge.timeline0.org/Smartup_Zero/3_1_leadership_team/issues/51) - [x] [6_1_6_0 - Old engelbot up and running in forge and in element.](CREATE_MANUALLY) - [x] [6_2_6_0 - Worker Command Suite ready](CREATE_MANUALLY) - [x] [6_3_6_0 - Multiple repo/room activity](CREATE_MANUALLY) - [x] [6_4_6_0 - engelbot command ledger](CREATE_MANUALLY) - [x] [6_5_6_0 - Engelbot and Forgejo API](CREATE_MANUALLY) - [x] [6_6_6_0 - Engelbot task creation with forgejo issue publishing](CREATE_MANUALLY) - [x] [6_7_6_0 - Cancel command mid conversation](https://forge.timeline0.org/Smartup_Zero/3_1_leadership_team/issues/33) - [x] [6_8_6_0 - Engelbot v1.0 - Production Deployment on Clever Cloud](https://forge.timeline0.org/Smartup_Zero/3_1_leadership_team/issues/34) - [x] 6_9_6_0 - ~~Test Task~~ (CANCELLED)  ## Progress (Autogenerated)  **Progress: 100%** (12/12 tasks complete) | Status | Count | |--------|-------| | ✅ Complete | 12 | | ❌ Cancelled | 2 (excluded) | **Last Activity:** 2025-10-09 by @robbert **Health:** 🔴 Inactive