Sovereign AI Software Factory

Architecture, Governance and Implementation Plan

Model-agnostic, open-source-first, self-hosted and energy-responsible development factory

Field Value

Purpose Decision and implementation report for team review before production rollout

Owner Joao Brazao

Version v2.0 draft

Date 2026-04-28

Status Draft for review; not yet approved

+-----------------------------------------------------------------------+ | Important framing | | | | This is not a vendor selection memo. It defines a sovereign operating | | model where AI models and development tools are interchangeable | | components. The durable assets are memory, governance, source | | control, task discipline, ingestion gates and deployment controls. | +=======================================================================+

Table of Contents¶

Executive Summary
Strategic Intent and Design Principles
Current Operating Model
Target Operating Model
Core Architecture
Sovereign Memory Layer
Six Eyes External Information Ingestion Gate
AI Routing Governor and Responsible Compute Policy
Tool Roles and Recommended Adoption
Standard Workflows
Implementation Roadmap
Transition Plan
Governance, Security and Risk Controls
Validation Checklist Before Production
Appendices: Templates and Prompts
References

1. Executive Summary¶

The objective is to build a sovereign AI-assisted software factory: a development operating model that lets the team specify, plan, build, test, review, release and maintain software rapidly while remaining independent from any single AI vendor, cloud platform or proprietary development environment.

The factory is open-source-first, self-hosted-first and Git-first. Forgejo is the source of truth for code, project memory, architectural decisions, prompts, agent definitions and operational documentation. Vikunja is the task and workflow board. LiteLLM is the mandatory LLM gateway and routing layer. Docker, Postgres, Vaultwarden, sandbox environments and controlled deployment pipelines form the operational base.

The key architectural shift is to move memory, governance and process above individual AI tools. Claude, ChatGPT/Codex, Gemini, DeepSeek, Minimax, local models, OpenHands, Aider, OpenClaw/Paperclip and future tools are replaceable workers. They request context from the Sovereign Memory Layer, perform scoped work, and return structured updates.

The factory includes a mandatory ingestion gate. Any information scraped or imported from the internet, YouTube, Instagram, news sites, technical documents, repositories, research papers or AI outputs must be evaluated using the Six Eyes Critical Thinking Framework before entering production memory, RAG indexes, decision pipelines or agent context.

A second governance layer is the responsible compute policy: use the minimum sufficient intelligence for each task. The system should prefer deterministic tools over LLMs, local and smaller models over frontier models when adequate, and escalate only when complexity, risk or failure justifies it.

2. Strategic Intent and Design Principles¶

2.1 Why this exists¶

AI coding tools are improving too quickly to anchor the factory in a single vendor or model.
The aim is not just faster coding; it is disciplined specification, shared memory, safe execution, responsible compute use and auditable decisions.
Models are engines. The team-owned memory, source control, workflows and policies are the chassis.

2.2 Non-negotiable principles¶

Principle Meaning

Sovereignty Critical infrastructure, memory, source control and workflows remain under team control.

Open-source-first Prefer open-source and self-hostable components unless an exception is justified.

Forgejo as source of truth Code, documentation, prompts, agent definitions, decisions and memory artifacts are versioned in Forgejo.

LiteLLM as gateway Production LLM calls go through LiteLLM rather than direct provider calls.

Model agnosticism Claude, Codex, Gemini, local models, DeepSeek, Minimax and future models are interchangeable engines.

Planning before execution Non-trivial work must pass through a planning gate before code is changed.

Sandbox before production All changes are tested in sandbox/staging before production promotion.

Six Eyes before ingestion External information is evaluated before entering production memory or decision pipelines.

Minimum sufficient intelligence Use the smallest safe capability that can complete the task.

Human approval for irreversible Production deployments, destructive actions migrations and high-risk changes require explicit human approval.

3. Current Operating Model¶

3.1 Existing assets¶

Asset Role

Forgejo Self-hosted Git/forge source of truth.

Vikunja Task manager for pending work, severity and urgency.

LiteLLM LLM gateway and production API abstraction.

Docker Component isolation and deployment.

Postgres Core data platform.

Vaultwarden Password and secret management.

Sandbox environment Pre-production testing environment.

Paperclip/OpenClaw ecosystem Agent and skill orchestration.

Mac mini LLM server Planned local LLM compute, mediated through LiteLLM.

3.2 Main gaps to solve¶

Cross-tool memory must survive movement between ChatGPT, Claude Code, OpenHands, Aider, OpenClaw and future tools.
External information needs rigorous evaluation before contaminating production knowledge.
Task routing must minimize token, cost and energy waste.
Execution should move from Vikunja to Forgejo branch, sandbox, review and production with auditability.
Agent permissions must be scoped to branches and sandboxes, not direct production access.

4. Target Operating Model¶

+-----------------------------------------------------------------------+ | Target outcome | | | | A model-agnostic development factory where humans define goals and | | approve risks, Forgejo stores truth, Vikunja drives work, LiteLLM | | routes intelligence, the Sovereign Memory Layer preserves context, | | and agents execute only within controlled scopes. | +=======================================================================+

Step Stage Description

1 Idea or issue appears A human, monitoring process, support input or agent creates a candidate task.

2 Ingestion/evaluation if External source is external normalized, claim-extracted and evaluated through Six Eyes.

3 Task creation Vikunja task is created/updated with project, severity, priority, type and risk.

4 Context package Sovereign Memory Layer exports project/task context.

5 Planning gate Planning model/tool produces plan or Command Brief without changing code.

6 Approval Human or policy approval authorizes execution.

7 Execution Agent works in branch and sandbox.

8 Review Different model/tool or human reviews the diff.

9 CI/CD and sandbox Tests, scans and smoke validation checks run.

10 Memory update Session summary, decisions, risks and next steps are written back.

5. Core Architecture¶

Human / Team\ -> Vikunja task board\ -> Sovereign Memory Layer\ -> AI Routing Governor\ -> LiteLLM\ -> AI tools and agents\ -> Forgejo branches, docs and reviews\ -> CI/CD + Docker sandbox\ -> Staging\ -> Production with human approval

Component Role Recommendation

Forgejo Canonical Git, docs, Core / already used prompts, ADRs,
branches, reviews,
releases

Vikunja Task intake, backlog, Core / already used severity, priority and
status

LiteLLM Unified LLM gateway, Core / already used provider abstraction,
fallback, budgets

Sovereign Memory API Context export/import, Build as MVP session summaries,
decisions, risks

Postgres + Structured memory and Build as MVP/Phase 2 pgvector/Qdrant semantic retrieval

AI Routing Governor Minimum sufficient Build after memory MVP intelligence policy and model tier selection

OpenHands Autonomous development Evaluate in sandbox worker in sandbox

Aider Git-native coding Adopt early assistant

Continue.dev Optional editor-based Optional model-agnostic
interface

Paperclip/OpenClaw Higher-level Integrate gradually orchestration of agents and skills

6. Sovereign Memory Layer¶

The Sovereign Memory Layer prevents context fragmentation across AI tools. It stores durable identity, factory rules, project context, decisions, risks, task history, session summaries and AI run metadata in infrastructure controlled by the team.

Memory type Storage Use

Cold memory Markdown in Forgejo Architecture, ADRs, policies, project context, prompts and command briefs

Warm memory Postgres Tasks, sessions, decisions, risks, model runs and deployments

Semantic memory pgvector or Qdrant Retrieval by meaning across docs, sessions and issues

Operational memory Vikunja + CI logs Current task status, severity, blockers and validation results

GET /context/user-profile\ GET /context/factory-rules\ GET /context/project/{project_id}\ GET /context/task/{task_id}\ POST /memory/session-summary\ POST /memory/decision\ POST /memory/risk\ POST /memory/incident\ POST /memory/model-run\ POST /memory/ingestion-evaluation

factory context APP1 APP1-0042 --for claude-code\ factory context APP1 APP1-0042 --for chatgpt\ factory remember session-summary.md\ factory task sync APP1-0042 --vikunja --forgejo

7. Six Eyes External Information Ingestion Gate¶

+-----------------------------------------------------------------------+ | Mandatory rule | | | | No external information enters production knowledge, RAG indexes, | | agent context, decision pipelines or generated outputs until it has | | passed a Six Eyes evaluation proportional to its stakes. | +=======================================================================+

7.1 Scope¶

Web pages, blogs, news articles and opinion pieces
YouTube transcripts and descriptions
Instagram and other social media content
Technical documentation
GitHub/GitLab/Forgejo repositories and READMEs
Research papers, datasets and market reports
Third-party internal documents
AI-generated outputs from any model

7.2 Six Eyes dimensions¶

Lens Core question Primary threat

Attention What is shown and what Strategic omission is hidden?

Emotion What am I being made to Affective bypass feel, and why?

Framing What conceptual Pre-loaded conclusions container is imposed?

Structure Does the False logical argument/evidence connections architecture hold?

Contrast What does this look Decontextualized data like against wider
references?

Integrity Who is behind it, what Undisclosed interest do they want, and are
they consistent?

7.3 Scoring and disposition¶

Condition Meaning Action

0-3 on a lens High manipulation Quarantine for human signal review

4-6 on a lens Moderate concern Flag or accept with caveats depending on stakes

7-10 on a lens Low concern Eligible for ingestion if other controls pass

Composite \< 5.0 Insufficient overall Flag for human review trust

Any lens \< 3.0 Catastrophic Automatic quarantine single-lens failure regardless of average

7.4 Source-specific pipelines¶

Source type Required ingestion path

News / social / YouTube / Instagram Extract text/transcript -> metadata -> claim extraction -> Six Eyes scoring -> cross-source contrast -> accept/flag/quarantine

Technical documentation Version check -> source integrity -> claim extraction -> Six Eyes scoring -> compatibility/security review -> ingest

Open-source repository License check -> maintainer/integrity review -> security scan -> Six Eyes evaluation -> mirror into Forgejo -> sandbox test

AI-generated output Record model/tool -> claim extraction -> Six Eyes scoring -> verify critical claims -> store as provisional unless verified

{\ \"source_id\": \"SRC-001\",\ \"source_type\": \"technical_documentation\",\ \"six_eyes_scores\": {\"attention\": 7, \"emotion\": 8, \"framing\": 6, \"structure\": 8, \"contrast\": 5, \"integrity\": 7},\ \"composite_score\": 6.83,\ \"disposition\": \"accepted_with_caveats\",\ \"human_override\": false\ }

8. AI Routing Governor and Responsible Compute Policy¶

+-----------------------------------------------------------------------+ | Responsible compute principle | | | | Use the minimum sufficient intelligence: deterministic tools before | | LLMs, local/smaller models before frontier models, and escalation | | only when complexity, risk or failure justifies it. | +=======================================================================+

Tier Class Use cases

0 No LLM Formatting, parsing, tests, health checks, deterministic validation

1 Local small model Classification, extraction, simple summaries

2 Local medium/open model Simple code edits, documentation, task triage

3 Cheap/free cloud model Moderate planning, non-critical review

4 Strong model Complex coding, architecture, difficult bugs

5 Multi-model committee Security, auth, payments, migrations, production incidents

Task arrives -> classify type/risk/privacy/complexity/context -> choose smallest safe tier -> route via LiteLLM alias -> log tokens/cost/latency/outcome -> escalate only if validation fails or risk requires it

8.1 Mandatory strong-model or committee cases¶

Authentication and authorization
Security-sensitive code
Secrets or permissions changes
Payment logic
Destructive database migrations
Production incidents
Public API contract changes
Legal/compliance-sensitive text

model_runs: run_id, project_id, task_id, tool, model_alias, actual_model, tier, input_tokens, output_tokens, estimated_cost, energy_class, latency_ms, success, quality_score, escalation_reason, created_at

9. Tool Roles and Recommended Adoption¶

Tool Role Recommendation

Forgejo Source of truth Core. Store code, docs, prompts, ADRs, decisions and memory artifacts.

Vikunja Task board Core. Use structured task IDs and severity/priority labels.

LiteLLM LLM gateway Core. Add aliases, budgets, fallbacks and telemetry.

Sovereign Memory API Shared memory Build. This is the strategic missing layer.

AI Routing Governor Responsible model Build after memory MVP. selection

Aider Git-native coding Learn first for small assistant controlled changes.

OpenHands Autonomous coding Evaluate in sandbox worker only.

Continue.dev Editor assistant Optional visual code exploration.

OpenClaw/Paperclip Orchestration and Use above workers, not skills as source of truth.

Claude Code / Codex / Premium engines Use through policies Gemini and context packages.

10. Standard Workflows¶

10.1 New project workflow¶

Create project record and repository in Forgejo.
Create Vikunja project/list and severity labels.
Run Project Vision Interrogator to produce approved Command Brief.
Commit Command Brief, PROJECT.md, MODEL_CONTEXT.md and initial ADRs.
Generate context package for implementation agent.
Create branch and sandbox environment.
Implement with tests and reviews.
Promote only after sandbox validation and human approval.

10.2 Non-trivial task workflow¶

Task created or selected in Vikunja.
Memory context generated for the task.
Planning agent produces a plan without changing code.
Human or policy approval starts execution.
Execution agent creates branch and implements in sandbox.
Separate reviewer model/tool reviews diff and risks.
CI/CD runs tests, scans and smoke checks.
Session update and memory update are committed to Forgejo.

10.3 External information ingestion workflow¶

Scrape/import source into raw quarantine zone.
Normalize text and capture metadata.
Extract atomic claims.
Run Six Eyes scoring.
Apply accept/flag/quarantine rules.
Human review and override if needed.
Only accepted information enters production memory/RAG/agent context.

11. Implementation Roadmap¶

Phase Name Deliverables Size

0 Approve operating Approve report, owners, S rules terminology and MVP
scope

1 Memory Forgejo folder M foundations structure, templates,
MODEL_CONTEXT.md, ADRs

2 LiteLLM aliases Aliases, budgets, M and telemetry fallbacks and
model_runs table

3 Six Eyes Manual/semi-automated M ingestion MVP scoring, quarantine
workflow

4 Sovereign Memory Context export/import L API and session updates
using Postgres

5 Aider adoption Controlled small tasks S through Forgejo
branches

6 OpenHands sandbox Test on sandbox repos M evaluation only with LiteLLM and
context packages

7 AI Routing Task classification, L Governor MVP tier selection and
escalation logging

8 Vikunja/Forgejo Task IDs, branch links, M integration review and deployment
status

9 CI/CD and Sandbox validation, L promotion staging and human
controls production approval

12. Transition Plan from Current Model¶

Week 1: Stabilize conventions¶

Create standard repo folders for docs, ADRs, prompts, agents, sessions, reviews and policies.
Add MODEL_CONTEXT.md to active projects.
Make Project Vision Interrogator the official planning gate for new projects and major tasks.
Define task ID convention linking Vikunja, Forgejo branches, commits and session summaries.

Week 2: LiteLLM and routing¶

Define aliases: triage, planner, coder_basic, coder_strong, reviewer, local_private, embeddings.
Set budget, fallback and escalation policies.
Start logging model runs and token/cost metadata.
Write AI Routing Policy in Forgejo.

Week 3: Six Eyes ingestion MVP¶

Create ingestion statuses: raw, normalized, evaluated, accepted, flagged, quarantined, overridden.
Implement Six Eyes scoring template.
Apply manually to five real sources before automating.
Define what may enter production memory.

Week 4: Memory API and first integration¶

Build minimal API for profile, factory rules, project context, task context and session summaries.
Create factory context and factory remember CLI commands.
Integrate Aider first, then test OpenHands in sandbox.
Run one end-to-end task from Vikunja to branch, review, sandbox and memory update.

13. Governance, Security and Risk Controls¶

Risk Likelihood Impact Mitigation

Tool lock-in Medium High Keep memory, routing, docs and source control outside individual tools.

Memory High High Mandatory Six Eyes gate contamination by and quarantine rules. weak sources

Excessive model High Medium AI Routing Governor, spend or energy tiering, budgets and waste escalation reasons.

Agent changes Medium High Sandbox-only execution, production branch protection and directly human approval.

Secrets leak to Medium High Vaultwarden, secret external models redaction, local/private routing for sensitive context.

Overengineering Medium Medium Start with MVP memory, before value manual Six Eyes scoring and Aider.

False confidence Medium High Separate from AI reviews implementation/review models, tests and human approval.

Fragmented task Medium Medium Universal task ID tracking across Vikunja, Forgejo, branches, commits and memory.

14. Validation Checklist Before Production¶

Architecture approval¶

[ ] Forgejo confirmed as source of truth
[ ] Vikunja workflow agreed
[ ] LiteLLM aliases approved
[ ] Memory API scope approved
[ ] Sandbox-to-production policy approved

Memory readiness¶

[ ] USER_PROFILE.md exists
[ ] FACTORY_RULES.md exists
[ ] MODEL_CONTEXT.md exists per project
[ ] Session summary template exists
[ ] ADR template exists

Ingestion readiness¶

[ ] Six Eyes scoring template implemented
[ ] Quarantine status implemented
[ ] Audit trail defined
[ ] Human override process defined
[ ] At least five sample sources evaluated

Routing readiness¶

[ ] Model tiers defined
[ ] Budgets defined
[ ] Escalation rules defined
[ ] Telemetry logging enabled
[ ] High-risk direct-to-strong-model rules defined

Execution readiness¶

[ ] Aider tested on sandbox repo
[ ] OpenHands tested in sandbox only
[ ] CI/CD smoke tests exist
[ ] Production approval gate works
[ ] Rollback procedure documented

15. Appendices: Templates and Prompts¶

15.1 Context loading prompt¶

Load the sovereign context for project {PROJECT_ID} and task {TASK_ID}.\ Use the external memory package as the source of truth.\ Do not rely on your internal memory of this project.\ Before proposing changes, summarize what you understand and list any uncertainty.

15.2 Planning gate prompt¶

Analyze task {TASK_ID}.\ Do not change files. Do not scaffold code. Do not run destructive commands.\ Produce a plan covering objective, assumptions, affected components, proposed changes, tests, risks, rollback and approval requirements.

15.3 Session memory update prompt¶

Prepare a sovereign memory update including project_id, task_id, tool/model, decisions, files changed, commands/tests run, risks, next steps and what another model needs to know to continue. Return Markdown plus structured JSON.

15.4 Minimum sufficient intelligence snippet¶

Use deterministic tools when sufficient. Use local/smaller models when sufficient. Escalate only when complexity, risk or failure justifies it. Log tier, tokens, cost, latency and escalation reason. For high-risk work, require review and human approval.

16. References¶

Joao Luis Brazao, Six Eyes Critical Thinking Framework, Version 1.0, Canonical Reference. Uploaded internal document.
Joao Brazao, Project Vision Interrogator v4.0.0, Sovereign Project Interrogation Protocol. Uploaded internal document.
LiteLLM official documentation: proxy server, routing, fallbacks and provider/model budget routing.
Forgejo official documentation and project site: self-hosted lightweight software forge.
Vikunja official site and documentation: open-source, self-hostable task management.
OpenHands official repository and documentation: open-source AI software development agent and agent SDK.
Aider documentation: Git-native AI pair programming assistant.
Continue.dev documentation: customizable AI coding assistant with multiple model providers.

+-----------------------------------------------------------------------+ | Approval gate | | | | This document is a draft for team review. It should not be treated as | | an approved implementation plan until the team validates the | | principles, roadmap, governance controls and MVP scope. | +=======================================================================+