a4db3e62ec
Addresses the documentation-layer gap after Phase A/B moved the git REMOTE from
GitHub to Codeberg but left ~100 project-self GitHub URLs embedded in markdown,
HTML, JS, and Python files. The remote-layer migration was generalised as
"GitHub is gone from the codebase" without verifying the content layer.
22 files swept in this commit. 27 additional files hold pre-existing inst_016/017/018
or inst_084 debt that would transfer on touch (hook whole-file scan). Those
await a companion hygiene-first commit before their GitHub->Codeberg flip
can land cleanly.
Sweep scope this commit:
- README.md, SECURITY.md
- 3 For-Claude-Web bundle files (GitHub URLs noted as "separate concern" in
today's earlier licence-swap commits)
- docs/markdown/deployment-guide.md
- docs/AUTOMATED_SYNC_SETUP, PLURALISM_CHECKLIST, github/AGENT_LIGHTNING_README
- docs/business-intelligence/governance-bi-tools
- docs/outreach/EXECUTIVE-BRIEF-BI-GOVERNANCE (+ v2)
- docs/research/ARCHITECTURAL-SAFEGUARDS-*
- email-templates/README.md, base-template.html
- 3 scripts/seed-*-blog-post.js (blog-seeding scripts)
- scripts/upload-document.js
- SESSION_HANDOFF_2025-10-23_FRAMEWORK_ANALYSIS.md
- SECURITY_INCIDENT_POST_MORTEM_2025-10-21.md
Pattern swaps (longest-first):
github.com/AgenticGovernance/tractatus-framework/issues -> codeberg.org/mysovereignty/tractatus-framework/issues
github.com/AgenticGovernance/tractatus-framework/discussions -> .../issues (Codeberg has no discussions feature)
github.com/AgenticGovernance/tractatus-framework.git -> codeberg.org/mysovereignty/tractatus-framework.git
github.com/AgenticGovernance/tractatus-framework -> codeberg.org/mysovereignty/tractatus-framework
git@github.com:AgenticGovernance/... -> git@codeberg.org:mysovereignty/...
github.com/AgenticGovernance/tractatus (old org/repo path) -> codeberg.org/mysovereignty/tractatus-framework
AgenticGovernance/tractatus-framework (bare) -> mysovereignty/tractatus-framework
Hook validator update (scripts/hook-validators/validate-credentials.js):
PROTECTED_VALUES.github_org: 'AgenticGovernance' -> 'mysovereignty'
PROTECTED_VALUES.license: 'Apache License 2.0' -> EUPL-1.2 long form
URL detection regex: /github\.com\/.../ -> /codeberg\.org\/.../
Placeholder checks + error messages updated to reflect Codeberg as
authoritative post-migration host. Key names (e.g. `github_org`) retained
for backward compatibility with validate-file-edit.js.
Held back from this commit (27 files total, documented reasons):
11 historical session handoffs / closedown docs / incident reports
(2025-10 through 2026-02) — modifying them rewrites the record to contain
URLs that did not exist at the time of writing, AND ownership of their
pre-existing inst_084 exposures transfers on touch.
8 live-content docs with pre-existing inst_084 debt (port/API-endpoint/
file-path exposures): docs/markdown/case-studies.md, technical-architecture,
introduction-to-the-tractatus-framework, implementation-guide-v1.1,
docs/plans/integrated-implementation-roadmap-2025, docs/governance/*,
docs/ANTHROPIC_*, docs/GOVERNANCE_SERVICE_*, docs/RESEARCH_DOCUMENTATION_*,
deployment-quickstart/*.
8 live-content docs with pre-existing inst_016/017/018 debt:
CHANGELOG.md, CONTRIBUTING.md, docs/LAUNCH_ANNOUNCEMENT, LAUNCH_CHECKLIST,
PHASE_4_REPOSITORY_ANALYSIS, PHASE_6_SUMMARY, docs/plans/research-enhancement-
roadmap-2025, docs/case-studies/pre-publication-audit-oct-2025.
Also NOT in this commit (separate concerns):
- scripts/add-inst-084-github-url-protection.js (detection-rule logic needs
framework-level decision on post-migration semantics).
- .claude/* (framework state).
- docs/PRODUCTION_DOCUMENTS_EXPORT.json (DB dump).
- package-lock.json (npm sponsor URLs, third-party).
- .git/config embedded credentials (requires out-of-band rotation on both
remote hosts + auth-strategy decision; user-action task).
Context: today's EUPL-1.2 sweep closed the licence-text-content layer
(5c386d0d / 6d49bfbf / ab0a6af4 / 4c1a26e8). This commit starts closing the
matching vendor-URL-content layer. Next: hygiene-first pass on the 16
live-content docs held back, then a second URL-flip pass on them.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
279 lines
12 KiB
Markdown
279 lines
12 KiB
Markdown
# Agent Lightning Integration
|
||
|
||
**Governance + Performance: Can safety boundaries persist through reinforcement learning optimization?**
|
||
|
||
[](https://opensource.org/licenses/Apache-2.0)
|
||
[](https://agenticgovernance.digital/integrations/agent-lightning.html)
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
This repository documents the integration of the **Tractatus governance framework** with **Microsoft's Agent Lightning** reinforcement learning optimization framework.
|
||
|
||
**Core Question**: When AI agents learn and optimize autonomously through RL, can architectural governance constraints remain effective, or do they degrade over time?
|
||
|
||
**Preliminary Answer (Small-Scale)**: Demo 2 shows 5% performance cost for 100% governance coverage across 5 training rounds with 1 agent. Scalability testing required to validate production viability.
|
||
|
||
📖 **Full Technical Details**: [agenticgovernance.digital/integrations/agent-lightning.html](https://agenticgovernance.digital/integrations/agent-lightning.html)
|
||
|
||
---
|
||
|
||
## What is Agent Lightning?
|
||
|
||
**Agent Lightning** is Microsoft's open-source framework for using **reinforcement learning (RL)** to optimize AI agent performance. Instead of static prompts, agents learn and improve through continuous training on real feedback.
|
||
|
||
### Traditional AI Agents vs Agent Lightning
|
||
|
||
| Traditional AI Agents | Agent Lightning |
|
||
|----------------------|----------------|
|
||
| ❌ Fixed prompts/instructions | ✅ Learns from feedback continuously |
|
||
| ❌ No learning from mistakes | ✅ Improves through RL optimization |
|
||
| ❌ Manual tuning required | ✅ Self-tunes strategy automatically |
|
||
| ❌ Performance plateaus quickly | ✅ Performance improves over time |
|
||
|
||
### The Governance Problem
|
||
|
||
When agents are learning autonomously, how do you maintain governance boundaries? Traditional policies fail because agents can optimize around them. This integration explores whether **architectural enforcement** can solve this problem.
|
||
|
||
---
|
||
|
||
## Two-Layer Architecture
|
||
|
||
We separate governance from optimization by running them as **independent architectural layers**. Agent Lightning optimizes performance _within_ governance constraints—not around them.
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ LAYER 1: GOVERNANCE (Tractatus) │
|
||
│ ✓ Validates every proposed action │
|
||
│ ✓ Blocks constraint violations │
|
||
│ ✓ Enforces values boundaries │
|
||
│ ✓ Independent of optimization │
|
||
│ ✓ Architecturally enforced │
|
||
└──────────────────────────────────────────────────────────┘
|
||
↓
|
||
[Approved Tasks]
|
||
↓
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ LAYER 2: PERFORMANCE (Agent Lightning) │
|
||
│ ✓ RL-based optimization │
|
||
│ ✓ Learns from feedback │
|
||
│ ✓ Improves task performance │
|
||
│ ✓ Operates within constraints │
|
||
│ ✓ Continuous training │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Key Design Principle
|
||
|
||
Governance checks run **before** AL optimization and **continuously validate** during training loops. Architectural separation prevents optimization from degrading safety boundaries.
|
||
|
||
---
|
||
|
||
## Demo 2: Preliminary Results
|
||
|
||
⚠️ **Validation Status**: These results are from **1 agent, 5 training rounds, simulated environment**. NOT validated at scale. Scalability testing required before drawing conclusions about production viability.
|
||
|
||
### Results
|
||
|
||
| Metric | Ungoverned | Governed | Difference |
|
||
|--------|-----------|----------|------------|
|
||
| **Performance (engagement)** | 94% | 89% | **-5%** |
|
||
| **Governance coverage** | 0% | 100% | **+100%** |
|
||
| **Constraint violations** | 5 | 0 | **-5 (all blocked)** |
|
||
| **Strategy** | Clickbait | Informative | **Values-aligned** |
|
||
| **Training stability** | Variable | Consistent | **More predictable** |
|
||
|
||
### Key Findings
|
||
|
||
- **-5%**: Performance cost for governance at small scale
|
||
- **100%**: Governance coverage maintained through 5 training rounds
|
||
- **0**: Constraint violations (all blocked architecturally)
|
||
|
||
### Interpretation
|
||
|
||
At small scale (1 agent, 5 rounds), architectural governance appears compatible with RL optimization. The 5% performance cost bought 100% constraint adherence and values alignment.
|
||
|
||
**The critical question: does this hold at scale?**
|
||
|
||
---
|
||
|
||
## Five Critical Research Gaps
|
||
|
||
These are the open questions we're actively investigating. If you're interested in collaborating, we'd love to hear from you.
|
||
|
||
### 1️⃣ Scalability of Governance Overhead
|
||
|
||
**Question**: Does the ~5% performance cost remain constant as we scale from 1 agent → 10 agents → 1000 agents?
|
||
|
||
**Current Data**: 5% cost observed at 1 agent, 5 rounds
|
||
**Limitation**: Only tested small-scale
|
||
**Research Need**: Test with 10 → 100 → 1000 agents at production scale
|
||
|
||
**Why it matters**: If overhead scales linearly, governance becomes prohibitively expensive at scale. If it's constant, governance is practically viable for production systems.
|
||
|
||
---
|
||
|
||
### 2️⃣ Long-term Boundary Persistence
|
||
|
||
**Question**: Do governance constraints remain effective through hundreds/thousands of RL training rounds?
|
||
|
||
**Current Data**: 100% constraint adherence across 5 rounds
|
||
**Limitation**: Very short training duration
|
||
**Research Need**: Long-term studies (1000+ rounds) tracking constraint drift
|
||
|
||
**Why it matters**: Instruction fade is a known problem. If boundaries degrade over time, governance fails silently—potentially catastrophically in production.
|
||
|
||
---
|
||
|
||
### 3️⃣ Adversarial Resistance
|
||
|
||
**Question**: Can agents learn to optimize around governance constraints?
|
||
|
||
**Current Data**: No adversarial testing performed
|
||
**Limitation**: Cooperative training environment only
|
||
**Research Need**: Stress testing with agents explicitly incentivized to bypass governance
|
||
|
||
**Why it matters**: If agents can learn to circumvent boundaries through clever optimization strategies, architectural governance is illusory. This is a critical failure mode.
|
||
|
||
---
|
||
|
||
### 4️⃣ Performance Gap Closure
|
||
|
||
**Question**: Does the 5% performance gap close with more training, or is it a persistent trade-off?
|
||
|
||
**Current Data**: Gap observed at round 5, no data beyond that point
|
||
**Limitation**: Insufficient training time
|
||
**Research Need**: Extended training (100+ rounds) to see if governed agents converge to ungoverned performance
|
||
|
||
**Why it matters**: If the gap persists, we need to quantify the cost-benefit clearly. If it closes, governance may be "free" long-term—dramatically changing adoption calculations.
|
||
|
||
---
|
||
|
||
### 5️⃣ Multi-Agent Coordination Under Governance
|
||
|
||
**Question**: How does architectural governance affect emergent coordination in multi-agent systems?
|
||
|
||
**Current Data**: Single-agent testing only
|
||
**Limitation**: No multi-agent scenarios tested
|
||
**Research Need**: Test collaborative and competitive multi-agent environments with architectural governance
|
||
|
||
**Why it matters**: Real-world agentic systems are multi-agent (customer service, logistics, research teams). Governance that works for one agent may fail when agents must coordinate. Emergent behaviors are unpredictable.
|
||
|
||
---
|
||
|
||
## Live Demonstration
|
||
|
||
🎯 **This Integration is Running in Production**
|
||
|
||
The feedback button on [agenticgovernance.digital](https://agenticgovernance.digital) demonstrates the Tractatus + Agent Lightning integration live. When you submit feedback:
|
||
|
||
1. **Governance Check**: Tractatus validates PII detection, sentiment boundaries, compliance requirements
|
||
2. **AL Optimization**: Agent Lightning learns patterns about useful feedback and response improvement
|
||
3. **Continuous Validation**: Every action re-validated. If governance detects drift, action blocked automatically
|
||
|
||
This isn't just a demo—it's a live research deployment. Your feedback helps us understand governance overhead at scale. Every submission is logged (anonymously) for analysis.
|
||
|
||
---
|
||
|
||
## Community & Resources
|
||
|
||
### 💬 Discord Communities
|
||
|
||
**Tractatus Discord** (Governance-focused)
|
||
- Architectural constraints
|
||
- Research gaps and collaboration
|
||
- Compliance and human agency
|
||
- Multi-stakeholder deliberation
|
||
|
||
👉 [Join Tractatus Server](https://discord.gg/Dkke2ADu4E)
|
||
|
||
**Agent Lightning Discord** (Technical implementation)
|
||
- RL optimization
|
||
- Integration support
|
||
- Performance tuning
|
||
- Technical questions
|
||
|
||
👉 [Join Agent Lightning Server](https://discord.gg/bVZtkceKsS)
|
||
|
||
### 📚 Documentation
|
||
|
||
- **Full Integration Page**: [agenticgovernance.digital/integrations/agent-lightning.html](https://agenticgovernance.digital/integrations/agent-lightning.html)
|
||
- **Tractatus Framework**: [agenticgovernance.digital](https://agenticgovernance.digital)
|
||
- **Agent Lightning**: [github.com/microsoft/agent-lightning](https://github.com/microsoft/agent-lightning)
|
||
|
||
---
|
||
|
||
## Research Collaboration
|
||
|
||
We're seeking researchers, implementers, and organizations interested in:
|
||
|
||
- ✓ Scalability testing (10+ agents, 1000+ rounds)
|
||
- ✓ Adversarial resistance studies
|
||
- ✓ Multi-agent governance coordination
|
||
- ✓ Production environment validation
|
||
- ✓ Long-term constraint persistence tracking
|
||
|
||
We can provide:
|
||
|
||
- ✓ Integration code and governance modules
|
||
- ✓ Technical documentation and architecture diagrams
|
||
- ✓ Access to preliminary research data
|
||
- ✓ Collaboration on co-authored papers
|
||
|
||
**Contact**: Join our Discord or use the feedback button at [agenticgovernance.digital](https://agenticgovernance.digital)
|
||
|
||
---
|
||
|
||
## Installation & Usage
|
||
|
||
### Prerequisites
|
||
|
||
- Python 3.12+
|
||
- Agent Lightning 0.2.2+
|
||
- Tractatus Framework (Apache 2.0)
|
||
|
||
### Quick Start
|
||
|
||
Full installation and integration instructions are available at:
|
||
📖 [agenticgovernance.digital/integrations/agent-lightning.html](https://agenticgovernance.digital/integrations/agent-lightning.html)
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
- **Tractatus Framework**: Apache License 2.0
|
||
- **Agent Lightning**: MIT License (Microsoft)
|
||
- **Integration Code**: Apache License 2.0
|
||
|
||
---
|
||
|
||
## Citation
|
||
|
||
If you use this integration in your research, please cite:
|
||
|
||
```bibtex
|
||
@software{tractatus_agent_lightning_2025,
|
||
title = {Agent Lightning Integration: Governance + Performance},
|
||
author = {Tractatus Project},
|
||
year = {2025},
|
||
url = {https://codeberg.org/mysovereignty/tractatus-framework},
|
||
note = {Preliminary findings (small-scale validation)}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Acknowledgments
|
||
|
||
- **Agent Lightning**: Microsoft Research for creating an excellent RL optimization framework
|
||
- **Community**: Early testers and collaborators in both Discord communities
|
||
- **Research Context**: This work explores open questions in AI governance, not solved problems
|
||
|
||
---
|
||
|
||
**Status**: Preliminary findings (small-scale validation)
|
||
**Integration Date**: October 2025
|
||
**Last Updated**: November 2025
|
||
|
||
**Philosophy**: Cite limitations, not just wins. This is open research, not marketing.
|