Forgejo: The Constitutional Ledger¶

TL;DR

Forgejo is the append‑only, Git‑based ledger that serves as the single source of truth for the entire Smartup Zero experiment. Every governance decision, task, transaction, and lesson is stored as plain text in a self‑hosted, EU‑sovereign repository.

This architecture is what makes Engelbart’s indicators of Collective IQ—particularly memory, learning, and coordination—measurable from machine‑readable telemetry rather than surveys.

🟢 Research Status: Operational Apparatus — Core component actively generating auditable experimental data.

Why Forgejo?¶

Most organisations store their records in proprietary databases owned by corporations outside their jurisdiction. Smartup Zero does the opposite.

Ground Rule #1 — Prove Your Work

If not logged, it didn't happen.

Forgejo is a self-hosted, EU-sovereign, open-source git platform — the same technology that powers software version control, repurposed here as a constitutional ledger. Every record is a file. Every change is a commit. Every commit is signed, timestamped, and permanently auditable by anyone with access.

No vendor lock-in. No proprietary APIs. No data leaving EU jurisdiction. Ever.

But Forgejo is more than an audit tool. It is the foundation for testing whether shared, permanent institutional memory actually improves a community’s Collective IQ. Because every action is logged in a queryable format, we can measure exactly how often new work builds on past knowledge (Search‑to‑Creation Ratio), how quickly newcomers orient themselves (Onboarding Velocity), and whether the group’s decisions remain consistent over time.

Open Source

Forgejo is fully open-source. The ledger infrastructure is owned by the community, not a corporation.
EU Sovereign

Hosted at forge.timeline0.org. All data resides on EU infrastructure under EU law.
Append-Only

Records are never deleted or overwritten. Every mutation is a new commit in an immutable git history.
Auditable by Default

Ground Rule #5: Act in the Open. Every change is traceable to an actor, a timestamp, and a script.

The Repository Structure¶

SmartupOS organises all of its work across repositories that mirror its governance layers. Each repo ID maps directly to the OSOT layer system.

graph TD
    ORG["🏛️ Smartup_Zero (Forgejo Org)"]

    ORG --> R1["1_general_forum\n📂 Public\nGovernance & MkDocs source"]
    ORG --> R2["2_workplace\n📂 Private\nThe Ledger — single source of truth"]
    ORG --> R3["3_X_team_repos\n📂 Private\n7 team repos (issues + scripts)"]
    ORG --> R37["3_7_operational_team\n📂 Private\nEngelbot source code"]
    ORG --> R31["3_1_leadership_team\n📂 Private\nToolbox scripts + API"]

Repo	Visibility	Purpose
`1_general_forum`	🌍 Public	Democracy layer. MkDocs source that auto-generates timeline0.org
`2_workplace`	🔒 Private	The Ledger. All CSV indexes + wiki markdown content
`3_1_leadership_team`	🔒 Private	Toolbox scripts, Flask API, constitutional enforcement
`3_7_operational_team`	🔒 Private	Engelbot (Node.js/TypeScript)
`3_X_team_repos`	🔒 Private	Team issues, objectives, task tracking (7 teams)

One Branch — Always Master

All repositories operate on a single master branch. There are no feature branches, no pull request debates. Changes are committed directly by authenticated scripts acting on behalf of verified owners.

The Ledger Architecture¶

Forgejo doesn't just store code — it stores every economic and governance event in Smartup Zero. The architecture separates indexing from content into two complementary layers.

This split is what makes Engelbart’s indicators 1 (Learning) and 2 (Memory) measurable. The CSV layer gives the machine fast, structured answers to queries like “how many new tasks reference previous objectives?”; the Markdown layer provides the full reasoning so humans can audit why a decision was made. Together they turn institutional memory into a queryable asset.

CSV Layer (The Index) Wiki Layer (The Content)

CSV files are the machine-readable index. They store IDs, statuses, budgets, role assignments, and short summaries — structured data that scripts can query and update atomically.

Every CSV row includes a wiki_path pointer to the full content.

Location: 2_workplace/currency-ledger/

File	What It Tracks
`ownership/book-of-owners.csv`	Every owner: alias, roles, SK balance, status
`ledger/objectives/registry.csv`	All objectives (global + team)
`ledger/task-management/task-budgets.csv`	All tasks: budget, status, assignment
`ledger/task-management/work_clock.csv`	Clock-in / clock-out events
`ledger/task-management/session_logs.csv`	Completed work sessions
`ledger/smartup-credits/transactions.csv`	Validated SC awards
`ledger/pending-sc/transactions.csv`	SC awaiting captain validation
`ledger/social-karma/transactions.csv`	SK awards and peer nominations
`ledger/treasury/balance.csv`	EUR + SC outstanding snapshots
`master-events.csv`	Complete audit trail — every action, every actor

Markdown files in wiki/ hold the human-readable full record — the Why, How, and What behind every task, objective, and role.

Scripts write markdown first, then update the CSV index. This write order is constitutional.

Entity	Wiki Path
Task	`wiki/6_tasks/{task_id}.md`
Objective	`wiki/5_objectives/{obj_id}/{obj_id}.md`
Role description	`wiki/4_roles/{role_id}/briefing/role_description.md`
Owner portfolio	`wiki/2_workplace/2_book_of_owners/portfolios/{alias}/`

Write Order is Constitutional

Markdown first → CSV second → master-events.csv last.
This sequence is enforced in every Toolbox script. Inverting it risks an index pointing to content that doesn't exist yet.

How the Ledger Feeds CIQ Measurement¶

Because every event is permanently recorded in a structured ledger, we can extract precise metrics for the experiment:

CIQ Indicator	Metric	Data Source in Forgejo
1. Learning	Search‑to‑Creation Ratio	Task wiki references to historical objectives, task‑budgets.csv
2. Memory	Onboarding Velocity	join_date in book‑of‑owners.csv vs. first task start in work_clock.csv
3. Integration	Contribution Velocity	created_date to completion in task‑budgets.csv + session_logs.csv
4. Self‑Understanding	Structure‑Function Alignment	master‑events.csv decisions vs. documented roles in book‑of‑owners.csv
5. Perception	Anomaly‑to‑Response Latency	Element logs (mirrored in Matrix) vs. task creation timestamps
8. Coordination	Task Assessment Distribution	quality_label and scores in session_logs.csv

This direct mapping from hypothesis to ledger to metric is what transforms Forgejo from a simple git server into a laboratory instrument.

How the Ledger Becomes the Public Site¶

The public-facing website you are reading now is generated directly from Forgejo.

flowchart LR
    F["2_workplace\n(Private Ledger)"]
    G["1_general_forum\n(Public Repo)"]
    M["MkDocs Build\n(Clever Cloud)"]
    W["timeline0.org\n(Public Website)"]

    F -->|"generate-public-pages.py\n(strips private data)"| G
    G -->|"git push → CI trigger"| M
    M -->|"mkdocs build"| W

generate-public-pages.py runs on a schedule and extracts only public-safe data from the private ledger — owner aliases (never real names), objective progress, task completion rates — and writes them as markdown into 1_general_forum. MkDocs then builds this into the site you're reading.

Transparency by Architecture

The pipeline enforces transparency structurally. Private data (identity mapping, real names, emails) cannot reach the public site — they live in a separate CSV that the generator never reads.

Conflict Safety & Immutability¶

Git's content-addressable storage makes every record tamper-evident. But a live system with multiple concurrent writers needs an additional safety layer.

SmartupOS uses SHA-based optimistic locking: before writing any CSV, the script reads the file's current SHA from Forgejo's API. If another script committed a change between the read and the write, Forgejo returns a 409 Conflict. The Toolbox retries automatically with exponential backoff.

This means: - No record is ever silently overwritten - Concurrent writes are safe by default - Every retry is a fresh read — data is always current

Technical: How SHA Locking Works in Practice

Every write operation in the Toolbox follows this flow:

# 1. Read current state + SHA (the lock token)
rows, sha = api.fetch_csv(repo, path, branch)

# 2. Modify in memory
def modifier(rows):
    rows.append(new_row)
    return rows

# 3. Write with retry — if SHA has changed, re-read and retry
api.write_with_retry(repo, path, modifier, commit_msg, actor, branch)
# Max 3 retries with exponential backoff. 409s are transparent to users.

The modifier function is designed to be idempotent — safe to call multiple times with the same input. Sequential IDs are derived inside the modifier after the fresh re-read, making them concurrency-safe even under contention.

Technical: The master-events.csv Audit Trail

Every mutation in SmartupOS — task creation, SC award, role assignment, clock-in — appends a row to master-events.csv. This file is the forensic record of the entire experiment.

timestamp | smartup_id | actor | script | event_type | ref_file | description

It is append-only by design. Scripts never use write_with_retry() on this file — they always use append_csv_row(), which routes to a special handler that preserves the file's immutable append semantics and legacy format.

Forgejo in the SmartupOS Stack¶

flowchart TD
    H["Human\n(Matrix / Element)"]
    E["Engelbot\n(Node.js / TypeScript)"]
    T["Toolbox API\n(Flask / Python)"]
    S["Toolbox Scripts\n(Python — constitutional enforcement)"]
    F[("Forgejo\nAll CSV ledgers\n+ Wiki markdown")]
    P["timeline0.org\n(MkDocs — public transparency)"]

    H -->|"!command"| E
    E -->|"HTTP POST"| T
    T -->|"python3 script.py"| S
    S -->|"Forgejo REST API\n(SHA-based locking)"| F
    F -->|"auto-generates"| P

Forgejo sits at the bottom of the stack — the gravitational centre. Every other component (Engelbot, the Toolbox, the public website) reads from or writes to it. It is never bypassed.

Next: The Back-Office in Detail

Forgejo is where records live. Engelbot is how owners interact with those records without ever touching a CSV directly. Element is where those interactions happen.

Hosted at forge.timeline0.org · Organisation: Smartup_Zero · All repos: EU-sovereign, open-source