Version: 1.2.2 Status: Live Last Updated: 2026-02-08
For rapid onboarding: See QUICK-START.md.
For full onboarding: See ONBOARDING.md.
This document provides a deep technical analysis of the GenAI R&D framework architecture. It's designed for architects, system designers, and engineers who need to understand:
- System design patterns and why they were chosen
- Tradeoffs in the architecture
- Scalability considerations and constraints
- Governance patterns and enforcement mechanisms
- Evolution strategy and future directions
Estimated Time: 45-90 minutes (thorough technical review)
The framework follows a three-tier hierarchy inspired by cloud architectures:
┌─────────────────────────────────────────────────────┐
│ SYSTEM LAYER (Constitutional Governance) │
│ ├── CONSTITUTION.md │
│ ├── GUARDRAILS.md │
│ ├── SHARED-RESPONSIBILITY.md │
│ └── COMPLIANCE.md │
└─────────────────────────────────────────────────────┘
▼ Inheritance & Cascading
┌─────────────────────────────────────────────────────┐
│ PLATFORM LAYER (Reusable Workflows & Protocols) │
│ ├── FRICTION-PROTOCOL.md │
│ ├── THINKING-VISIBILITY-PROTOCOL.md │
│ ├── SECURITY-PROTOCOL.md │
│ ├── AUDIT-ARCHITECTURE.md │
│ ├── IaT/ (Infrastructure-as-Text) │
│ └── Audit/ (Audit reports and logs) │
└─────────────────────────────────────────────────────┘
▼ Application Context
┌─────────────────────────────────────────────────────┐
│ APP LAYER (Project-Specific Implementations) │
│ ├── Alliance-to-Empire/ (Ideation) │
│ ├── One-Shot/ (R&D Methodology) │
│ ├── AI-Guardrails-and-Bias/ (Ethics) │
│ ├── Prince-of-Persia/ (Narrative) │
│ └── US-Gov/ (Government Efficiency) │
└─────────────────────────────────────────────────────┘
Why 3 Tiers?
- System Layer — Immutable principles that apply everywhere (like AWS SCPs)
- Platform Layer — Reusable patterns that reduce repetition (DRY principle)
- App Layer — Context-specific implementations with isolated failure domains
Tradeoff: More layers = more abstraction overhead vs. better separation of concerns.
Decision: 3 tiers balance governance with pragmatism; more layers would over-engineer.
| AWS Concept | This Framework | Implementation | Why |
|---|---|---|---|
| Organizations | Repository root | Central governance hub | Single source of truth |
| SCPs | GUARDRAILS.md | Boundary policies | Explicit deny rules |
| Shared Responsibility | SHARED-RESPONSIBILITY.md | Human vs. AI accountability | Clear ownership |
| Regions/AZs | Project folders | Blast radius isolation | Failures don't cascade |
| CloudTrail | DESIGN.md, CHANGELOG.md | Audit trail | Immutable history |
| Config Rules | Audit scripts | Compliance checks | Automated verification |
| Government Concept | This Framework | Implementation | Why |
|---|---|---|---|
| Declaration | MANIFESTO.md | Vision statement | Why we exist |
| Constitution | CONSTITUTION.md | Immutable principles | Foundational rules |
| Bill of Rights | GUARDRAILS.md | Protected boundaries | Non-negotiable limits |
| Separation of Powers | SHARED-RESPONSIBILITY.md | Checks & balances | Accountability split |
| Judicial Review | Audit/ | Compliance verification | Post-action review |
| Amendments | CHANGELOG.md | Evolution tracking | Controlled change |
Preventive Controls:
- GUARDRAILS.md → Red lines (explicit deny)
- SECURITY-PROTOCOL.md → Gatekeeper (risk-based throttling)
- SHARED-RESPONSIBILITY.md → Accountability boundaries
Detective Controls:
- Audit scripts → Markdown validation, link checking, metadata verification
- CHANGELOG.md → Version tracking and change history
- DESIGN.md → Construction audit trail
Corrective Controls:
- FRICTION-PROTOCOL.md → Cost/Value Gate (AK STOP)
- THINKING-VISIBILITY-PROTOCOL.md → Tier-2 logs for high-stake work
- Human review → Approval gates for P4-P7 priorities
Tradeoff: Manual audit invocation vs. automated CI/CD.
Decision: Manual for now (simplicity); automate when repo scales beyond single maintainer.
The audit system follows a fail-closed model inspired by security engineering:
Input → Raw Capture → Normalization → Diff → Hash
▼
Reasoning Log
▼
Output + Attestation
▼
Binding (AAK BIND)
▼
Integrity Check
▼
[PASS → Continue]
[FAIL → Caution Mode → Human Review]
- Authenticity: Capture raw inputs verbatim; hash and bind (Tier-2)
- Traceability: Link inputs → decisions → outputs → attestations
- Visibility: Structured reasoning summaries (not raw chain-of-thought)
- Integrity: Continuous checksums, anomaly detection, fail-closed gating
| Signal | Purpose | When to Use |
|---|---|---|
| AAK GO | Start Tier-2 audit logging | High-stake work (P4-P7) |
| AAK STOP | Stop logging; retain file | Task complete |
| AAK BIND | Bind log to output | Link reasoning to artifact |
| AAK SAVE | Checkpoint current state | Frequent state capture |
| AK GO | Proceed (no audit) | Low-stake work (P8-P10) |
| AK STOP | Pause and gate | Overwhelm or low-value signal |
- Tier-1: Standard work; minimal logging
- Tier-2: High-stake (P4-P7); full reasoning logs + bindings
- Tier-3: Reserved for future critical infrastructure (not yet implemented)
Tradeoff: Overhead of AAK signals vs. audit completeness.
Decision: Manual AAK for now; automatic triggers planned for P4+ workflows.
IaT treats infrastructure design as a text-based intake and transformation workflow:
Raw Idea (Human) → Intake Form → Checklist → SR Template
▼
Reference Architecture
▼
Decision Options (Pro/Con)
▼
Scoring Rubric → Selection
▼
Traceability Matrix
▼
Change Analysis (Delta)
Why IaT?
- Text-native: Works with AI and humans; version-controlled in Git
- Iterative: Refine at each step; no premature optimization
- Auditable: Every decision captured with rationale
Tradeoff: More upfront structure vs. faster unstructured brainstorming.
Decision: Use IaT for architectural decisions; skip for quick experiments.
The Friction Protocol manages energy and value in collaboration:
High Amplitude (Overwhelm) → Detect → Switch Protocol
▼
[Music | Emoji | Doc | Model | Timebox]
▼
Cost/Value Gate (AK STOP)
▼
Present: Quick (1 step) vs. Deep (diagnostic)
▼
Ask 1 question max → Wait
▼
Restore Neutral Baseline ("Zero")
Why Friction Protocol?
- Energy management: Prevent burnout in human; prevent hallucination loops in AI
- Value throttling: Stop low-value suggestions before they drain attention
- Multi-modal: Switch to music, emoji, or alternate model when words fail
Tradeoff: Context-switching overhead vs. stuck-state prevention.
Decision: Short-circuit loops early; switching is cheaper than continuing broken state.
| Constraint | Impact | Mitigation | Future |
|---|---|---|---|
| Single Maintainer | Bottleneck for approvals | Auto-approve within boundaries | Delegation model, succession plan |
| Manual Audit | No CI/CD integration | Scheduled runs | GitHub Actions automation |
| No External Deps Manifest | Tools undocumented | Internal dependencies mapped | Create tools manifest |
| Markdown-Only | No rendered docs site | Rich cross-linking | Optional docs site (low priority) |
| No Automated Versioning | Manual version bumps | CHANGELOG.md tracking | Semantic versioning automation |
| AAK Signal Overhead | Manual invocation | Clear P1-P10 prioritization | Auto-trigger for P4+ |
Current Scale: Single maintainer, R&D repo, ~100 docs, 13 projects
Short-Term Target (6 months): 2-3 contributors, CI/CD audit, external deps manifest
Long-Term Target (1 year): 5-10 contributors, automated versioning, delegation model
Scaling Strategy:
- Phase 1: Document gaps, onboarding paths (ONBOARDING.md, DEEP-DIVE.md) — Done
- Phase 2: CI/CD for audit, automated metadata checks — Next
- Phase 3: Delegation model, succession plan, external contributor guide — Future
Near-Term (1-3 months):
- CI/CD integration for audit scripts
- Automated metadata validation on commit
- External dependency manifest (python3, gh, git, scripts)
- AAK auto-trigger for P4-P7 workflows
- Centralized changelog consolidation
Mid-Term (3-6 months):
- GitHub Actions for audit on PR
- Branch policy automation (no admin bypasses)
- Automated link checking on commit
- Delegation model documentation
- Succession plan for single-maintainer bottleneck
Long-Term (6-12 months):
- Semantic versioning automation
- Executable tests for constitutional principles
- Optional docs site (MkDocs or Docusaurus)
- External issue tracker integration (optional)
- Multi-maintainer governance model
- Can constitutional principles be executable? (Tests that verify GUARDRAILS.md compliance)
- How to scale AAK signals without overhead? (Auto-detection of P4+ workflows)
- What's the right balance between automation and human judgment? (Governance vs. efficiency)
- Can audit be real-time? (Live compliance checks vs. post-action review)
Debate 1: Markdown-Only vs. Rendered Docs Site
- Pro Markdown: Git-native, version-controlled, diff-friendly
- Pro Docs Site: Better UX, searchability, navigation
- Current Decision: Markdown-only; docs site optional if external adoption grows
Debate 2: Manual AAK vs. Automated Triggers
- Pro Manual: Explicit control, no false positives
- Pro Automated: Less overhead, consistent application
- Current Decision: Manual for now; auto-trigger for P4+ planned
Debate 3: Single Maintainer vs. Delegation
- Pro Single: Fast decisions, consistent vision
- Pro Delegation: Scalability, resilience, diversity
- Current Decision: Single for R&D phase; delegation when external contributors join
Each project inherits from the constitutional layer and adapts as needed:
Alliance-to-Empire/
├── AI-PERSONA.md ← Custom AI instructions
├── PRINCIPLES.md ← Project-specific principles (extends CONSTITUTION.md)
├── TODO.md ← Project backlog
└── README.md ← Project overview
Inherits:
- CONSTITUTION.md (system)
- GUARDRAILS.md (system)
- SHARED-RESPONSIBILITY.md (system)
- FRICTION-PROTOCOL.md (platform)
Pattern 1: One-Shot Methodology
- Used in One-Shot/, AI-Guardrails-and-Bias/, Prince-of-Persia/
- Ingest full context → single-pass analysis → structured output
- Reduces orphan state and context loss
Pattern 2: Show & Tell
- Used in showtell/ for slide deck generation
- Source docs → YAML config → Markdown slides + exec summary
- Automates presentation creation from existing docs
Pattern 3: IaT Workflow
- Used in IaT/ for infrastructure design
- Text intake → templates → scoring → traceability
- Bridges idea → implementation with audit trail
By now, you should understand:
- System Architecture — 3-tier model (System → Platform → App)
- Governance Patterns — AWS and Constitutional parallels
- Audit Framework — Fail-closed integrity with AAK signals
- Workflow Patterns — IaT, Friction Protocol, One-Shot
- Scalability — Current constraints and evolution roadmap
- Integration — How projects inherit and extend the framework
Next Steps:
- For practical use → QUICK-START.md
- For comprehensive onboarding → ONBOARDING.md
- For contribution → CURRENT_NOTES_AND_TODOS.md
- For specific workflows → IaT/README.md, FRICTION-PROTOCOL.md
Questions or Feedback? Open an issue or refer to TONE-AND-INTENT.md for communication norms.
This framework is a living system. Contribute to its evolution. 🚀