tractatus/docs/architecture/ADR-001-public-repository-release-process.md

ADR-001: Public Repository Release Process

Status: Accepted Date: 2025-10-21 Decision Makers: User, Claude Code Consulted: Previous session handoffs, GitHub Release v3.5.0 experience Informed: Future sessions, potential contributors

---

Context

The Tractatus framework was developed as an internal project with extensive research documentation, governance exploration, and implementation code mixed together. To make the framework useful to the broader community, we needed to release a public version focused on implementation while protecting internal research and strategy.

Key Constraints:

• Internal repository contains proprietary governance research
• Public repository should be implementation-focused only
• Must appear professional to external users (world-class quality standard)
• Need to prevent "bad actor bias" (misrepresentation of framework purpose)
• GitHub is primary distribution channel

Triggering Events:

1. Framework reached production-ready state (v3.5)
2. Need to share implementation with potential adopters
3. Desire to enable community contributions
4. Educational purpose (demonstrate governance framework in practice)

---

Decision

We will maintain separate repositories with distinct purposes and content:

Internal Repository: AgenticGovernance/tractatus

• Purpose: Complete project including research, governance exploration, website
• Audience: Project team, internal development
• Content: Everything (code, research, governance docs, internal strategy, session handoffs)
• Visibility: Private or limited access

Public Repository: AgenticGovernance/tractatus-framework

• Purpose: Implementation framework for developers
• Audience: Developers, implementers, researchers wanting to use the framework
• Content: Implementation code, technical docs, API references, setup guides
• Visibility: Public, community-driven

Release Process: Multi-phase cleanup → Professional documentation → GitHub Release → Community features

---

Decision Drivers

Positive Drivers (Why separate repositories)

1. Security: Internal research and strategy must not be public
2. Clarity: Developers need implementation docs, not governance theory
3. Professionalism: Public repo must appear world-class (no internal clutter)
4. Prevent Misuse: "Bad actor bias" incident showed AI can misrepresent framework
5. Contribution Quality: Separate repos allow focused contribution guidelines

Negative Drivers (Risks of single repository)

1. Accidental Exposure: Easy to accidentally publish internal docs
2. Confusion: Mixed content creates unclear narrative
3. Attack Surface: Internal strategy exposed to potential adversaries
4. Maintenance Burden: Filtering what to sync increases complexity
5. Brand Risk: Unprofessional appearance damages credibility

---

Considered Alternatives

Alternative 1: Single Repository with Branch Separation

Approach: main branch public, internal branch private

Pros:

• Single repository to manage
• Easier to sync changes
• No duplication of core code

Cons:

• High risk of accidental merges
• Complex git workflow for contributors
• Still requires filtering commits
• Easy to leak internal content

Rejected because: Security risk too high, complexity not worth marginal convenience

---

Alternative 2: Monorepo with Public/Private Directories

Approach: Public repo clones only /framework directory

Pros:

• Clear separation in directory structure
• Single source of truth for framework code
• Automated sync possible

Cons:

• git submodules or subtree complexity
• Contributors see full structure (confusing)
• Risk of publishing wrong directory
• Difficult to review PRs cleanly

Rejected because: Complexity outweighs benefits, contributors confused by structure

---

Alternative 3: Fully Separate Repositories (CHOSEN)

Approach: Two independent repositories with manual sync

Pros:

• Complete isolation (security)
• Each repo has clear, focused purpose
• Professional appearance (no clutter)
• Simple mental model for contributors
• Flexibility to diverge if needed

Cons:

• Manual sync required for framework updates
• Potential for repos to drift
• Duplication of some documentation
• Extra maintenance overhead

Chosen because: Security and clarity outweigh maintenance cost

---

Implementation

Phase 1-7: Repository Cleanup (82% reduction)

Goal: Remove all non-implementation content from public repo

Phases:

1. Remove test data and credentials
2. Remove internal session handoffs
3. Remove governance research documents
4. Remove business strategy documents
5. Remove project-specific website code
6. Remove accidentally published scripts (95 scripts)
7. Remove broken imports and fix crashes
8. Fix critical startup crashes

Result: 615 files → 96 files (84% reduction), zero startup crashes

Key Learning: Each phase required systematic audit, not assumptions based on filenames

---

Phase 8: Professional Documentation Suite

Goal: Make repository appear world-class to external users

Documents Created:

1. CHANGELOG.md

• Format: Keep a Changelog (industry standard)
• Content: Complete v3.5.0 initial release notes with features, technical highlights, requirements
• Length: 158 lines
• Quality: Publication-ready, semantic versioning compliant

2. SECURITY.md

• Purpose: Security vulnerability reporting and best practices
• Content:
  • Reporting: security@agenticgovernance.digital
  • SLA: 48-hour acknowledgment
  • Supported versions table
  • Best practices (5 sections)
  • Compliance (OWASP Top 10)
  • Security audit history
• Length: 232 lines
• Quality: Professional, comprehensive

3. README.md Enhancements

• Additions:
  • 5 status badges (license, release, tests, Node.js, MongoDB)
  • Quick links section
  • Core services table with file links
  • 5 usage examples
  • API documentation section
  • Citation section (BibTeX for academics)
• Growth: 215 → 372 lines (73% increase)
• Quality: Professional, informative, actionable

---

Phase 9: GitHub Release v3.5.0

Goal: Provide stable release with downloadable packages

Created: https://github.com/AgenticGovernance/tractatus-framework/releases/tag/v3.5.0

Release Notes Contents:

• 6 core services with descriptions
• 4 support services
• 9 database models
• API endpoints summary
• Docker deployment instructions
• Testing infrastructure (17 tests passing)
• Security features
• Requirements (Node.js 18+, MongoDB 7.0+)

Auto-Generated Downloads:

• tractatus-framework-3.5.0.zip
• tractatus-framework-3.5.0.tar.gz

Benefit: Users can download stable release without git clone

---

Phase 10: Community Features

Goal: Enable community engagement

Enabled: GitHub Discussions

• URL: https://github.com/AgenticGovernance/tractatus-framework/discussions
• Purpose: Questions, implementation sharing, ideas
• Moderation: Manual review by project team

Future: Contribution guidelines, issue templates, PR templates (deferred)

---

Governance Rules Created

inst_028 (Original - Deprecated)

Text: "ONLY documentation and research materials MUST be synced to tractatus-framework public GitHub repository"

Issue: Too narrow, didn't prevent theoretical frameworks or governance guides

Status: Deprecated 2025-10-21 (consolidated into inst_063_CONSOLIDATED)

---

inst_062 (Original - Deprecated)

Text: "GitHub README.md must be reviewed weekly and 'Last Updated' date updated when material changes occur"

Issue: Separate from main public GitHub policy

Status: Deprecated 2025-10-21 (consolidated into inst_063_CONSOLIDATED)

---

inst_063 (Original - Deprecated)

Text: "Public GitHub (tractatus-framework) must remain implementation-focused. Prohibited without explicit approval: governance research, deliberation guides, theoretical frameworks..."

Context: Created after "bad actor bias" incident where AI converted implementation docs to authoritarian governance guide

Issue: Lacked weekly review requirement

Status: Deprecated 2025-10-21 (consolidated into inst_063_CONSOLIDATED)

---

inst_063_CONSOLIDATED (Current - Active)

Full Rule:

Public GitHub repository (tractatus-framework) must remain implementation-focused.

Prohibited without explicit approval:
1. Governance research documents
2. Pluralistic deliberation guides
3. Theoretical frameworks
4. Project-specific internal documentation
5. Business strategy documents

Allowed:
1. Technical implementation documentation
2. API reference guides
3. Code examples and tutorials
4. Installation/setup guides
5. Contribution guidelines

README.md must be reviewed weekly and "Last Updated" date updated when material
changes occur. README is primary external interface - must be world-class and current.

Quadrant: STRATEGIC Persistence: HIGH Scope: PERMANENT

Notes: Consolidated from inst_028, inst_062, inst_063. Created after bad actor incident where AI converted implementation docs to authoritarian governance guide. Prevents misrepresentation of framework purpose.

---

"Bad Actor Bias" Incident

What Happened

During public repository preparation, AI assistant suggested converting implementation documentation into "governance guide for preventing bad actors" - completely misrepresenting the framework's purpose.

Root Cause

AI pattern recognition associated "governance framework" with "preventing bad behavior" despite explicit instructions that Tractatus is about:

• Value pluralism (no single moral framework)
• Human decision-making (AI facilitates, doesn't decide)
• Explicit instructions over learned patterns (27027 failure mode)

Impact

If published, would have positioned framework as authoritarian control tool instead of pluralistic deliberation facilitator - exact opposite of actual purpose.

Response

1. Created inst_063 with explicit prohibited/allowed lists
2. Enhanced with weekly README review requirement
3. Added to CLAUDE.md as permanent warning
4. Documented in this ADR as key learning

Prevention

• inst_063_CONSOLIDATED now blocks governance-focused content
• Requires explicit user approval for any theoretical frameworks
• Weekly README reviews catch drift toward misrepresentation
• ADR documents correct positioning for future reference

---

Consequences

Positive Consequences

1. Security: Internal research protected, zero risk of accidental exposure
2. Clarity: Public repo has clear, focused purpose (implementation framework)
3. Professionalism: External users see world-class quality (badges, docs, releases)
4. Contribution Quality: Contributors understand framework is development tool, not governance theory
5. Brand Protection: inst_063_CONSOLIDATED prevents misrepresentation
6. Community Ready: Discussions enabled, professional appearance, downloadable releases

Negative Consequences

1. Manual Sync: Framework code changes must be manually synced between repos
2. Duplication: Some documentation exists in both repos (README, CONTRIBUTING)
3. Maintenance Overhead: Two repos to manage, update, monitor
4. Potential Drift: Repos could diverge if sync discipline lapses
5. Contributor Confusion: Contributors may not understand relationship between repos

Mitigation Strategies

For Manual Sync:

• Document sync process in internal CLAUDE.md
• Use git tags to track which versions synced
• Quarterly sync reviews to catch drift

For Duplication:

• Accept duplication as cost of clarity
• Keep duplicated docs minimal (README, LICENSE only)
• Use automation where possible (CI/CD for tests)

For Maintenance:

• Schedule weekly reviews per inst_063_CONSOLIDATED
• Use GitHub Actions for automated checks
• Leverage community for issue reporting

For Contributor Confusion:

• Clear README explanation of repository purpose
• Contribution guidelines specify scope
• Issue templates guide appropriate contributions

---

Metrics

Repository Reduction

• Before: 615 files (mixed content)
• After: 96 files (implementation only)
• Reduction: 84% fewer files
• Benefit: Clarity, professionalism, security

Documentation Quality

• README Growth: 215 → 372 lines (+73%)
• New Docs: CHANGELOG.md (158 lines), SECURITY.md (232 lines)
• Badges Added: 5 (license, release, tests, Node.js, MongoDB)
• Quality: Publication-ready, professional

Community Engagement

• GitHub Release: v3.5.0 with downloadable packages
• Discussions: Enabled (community questions, sharing, ideas)
• Contributors: Ready to accept (guidelines in place)

Governance

• Rules Created: inst_063_CONSOLIDATED (consolidated from 3 rules)
• Protection: "Bad actor bias" incident prevention
• Maintenance: Weekly README review requirement

---

Lessons Learned

1. Assumptions Are Dangerous

Observation: Initial cleanup phases assumed filenames indicated content Learning: Must READ files, not assume based on names Example: Files named "guide" contained implementation details, files named "implementation" contained theory

Applied: User repeatedly caught superficial cleanup, forced systematic audit

---

2. AI Pattern Recognition Can Misrepresent Purpose

Observation: AI suggested converting framework to "bad actor prevention" guide Learning: AI training creates strong associations that override explicit instructions Example: "Governance" → "preventing bad behavior" despite pluralistic values focus

Applied: Created inst_063 with explicit prohibited/allowed lists, weekly reviews

---

3. Professional Appearance Matters

Observation: Initial public repo lacked badges, changelog, security policy Learning: External users judge quality by presentation, not just code Example: No CHANGELOG.md signals "hobby project", not "production framework"

Applied: Created comprehensive documentation suite, GitHub Release with downloads

---

4. Separate Repositories Reduce Risk

Observation: Single repository with filtering creates accidental exposure risk Learning: Complete separation is simplest mental model, safest approach Example: Wrong directory sync could expose all internal research

Applied: Fully separate repos, manual sync with discipline over automation

---

5. Community Needs Clear Narrative

Observation: Mixed content creates confusion about framework purpose Learning: Public repo must tell coherent story: "development tool for AI safety" Example: Governance research dilutes implementation narrative

Applied: Public repo is implementation-only, clear README with purpose/examples

---

6. Weekly Reviews Prevent Drift

Observation: Repositories evolve over time, purpose can drift Learning: Regular reviews maintain alignment with intended positioning Example: README could gradually accumulate governance theory without oversight

Applied: inst_063_CONSOLIDATED requires weekly README review, "Last Updated" tracking

---

7. World-Class Quality Takes Iterations

Observation: User rejected multiple cleanup attempts as insufficient Learning: True quality requires systematic audit, not quick passes Example: 8 phases of cleanup, each catching issues previous phases missed

Applied: No shortcuts, no assumptions, comprehensive verification

---

Review Schedule

Weekly Reviews (per inst_063_CONSOLIDATED)

• What: README.md content and "Last Updated" date
• Who: Project team (human approval required)
• Check: Alignment with implementation focus, no governance theory drift

Monthly Reviews

• What: Public repository content audit
• Who: Project team
• Check: No internal docs accidentally published, documentation current

Quarterly Reviews

• What: Sync status between internal and public repos
• Who: Project team
• Check: Framework code in sync, public repo has latest stable implementation

Post-Release Reviews

• What: Community feedback, GitHub Discussions, issue tracker
• Who: Project team
• Check: Contributor understanding, purpose clarity, misrepresentation risk

---

Related Decisions

Supersedes

• None (first ADR in architecture/ directory)

Superseded By

• None (current)

Related ADRs

• ADR-002: Multi-project governance architecture (future)
• ADR-003: Continuous enforcement architecture (future)

Related Rules

• inst_063_CONSOLIDATED: Public GitHub management (active)
• inst_028: Original sync rule (deprecated)
• inst_062: Original README review rule (deprecated)
• inst_063: Original public GitHub rule (deprecated)

---

Appendix A: Public Repository Contents (v3.5.0)

Core Services (6)

1. InstructionPersistenceClassifier
2. CrossReferenceValidator
3. BoundaryEnforcer
4. ContextPressureMonitor
5. MetacognitiveVerifier
6. PluralisticDeliberationOrchestrator

Support Services (4)

1. MemoryProxyService
2. AuditService
3. GovernanceService
4. SchedulerService

Database Models (9)

1. GovernanceRule
2. Project
3. SessionState
4. AuditLog
5. GovernanceLog
6. MemoryEntry
7. ScheduledJob
8. TokenCheckpoint
9. DeliberationSession

Documentation Files (7)

1. README.md (372 lines)
2. CHANGELOG.md (158 lines)
3. SECURITY.md (232 lines)
4. LICENSE (Apache 2.0)
5. CONTRIBUTING.md
6. CODE_OF_CONDUCT.md
7. .gitignore

Total Files: 96 (down from 615)

---

Appendix B: Sync Process (Internal → Public)

When to Sync

1. Framework core services modified
2. Database models changed
3. API endpoints updated
4. Documentation improvements
5. Security fixes
6. Major features completed

What to Sync

• ✅ /src/services/ (framework components)
• ✅ /src/models/ (database schemas)
• ✅ /src/routes/ (API endpoints)
• ✅ /src/middleware/tractatus/ (framework enforcement)
• ✅ /tests/ (unit and integration tests)
• ✅ README.md, CHANGELOG.md, SECURITY.md
• ❌ /docs/governance/ (internal research)
• ❌ /docs/research/ (theoretical frameworks)
• ❌ .claude/ (session management)
• ❌ /scripts/ (internal tooling - most scripts)

How to Sync

1. Create feature branch in internal repo
2. Test thoroughly in internal environment
3. Create corresponding branch in public repo
4. Copy synced files (listed above)
5. Run tests in public repo
6. Create PR in public repo
7. Review for accidental internal content
8. Merge to public/main
9. Tag release if appropriate
10. Update CHANGELOG.md

Sync Checklist

• No internal research documents included
• No session handoffs or governance exploration
• No business strategy or project plans
• README.md "Last Updated" current
• CHANGELOG.md updated if release
• Tests passing in public repo
• No references to internal-only features
• Documentation focuses on implementation

---

Appendix C: "Bad Actor Bias" Prevention

Prohibited Content Examples

❌ "Governance framework for preventing bad actors" ❌ "Ensure AI systems behave correctly" ❌ "Enforce ethical behavior in autonomous agents" ❌ "Authoritative decision-making for AI safety" ❌ "Centralized control of AI values"

Allowed Content Examples

✅ "Development tool for implementing explicit instruction persistence" ✅ "Framework for maintaining human authority in AI-assisted decisions" ✅ "Facilitates pluralistic deliberation across value systems" ✅ "Prevents pattern recognition from overriding user instructions" ✅ "Enables value-aware AI systems with human oversight"

Detection Keywords (Review Triggers)

• "prevent bad actors"
• "enforce behavior"
• "ensure compliance"
• "authoritative control"
• "centralized governance"
• "correct AI behavior"

Correct Positioning

Tractatus IS: A development tool (like an IDE or linter) that helps implement AI systems respecting:

• Explicit instructions over learned patterns
• Human decision-making in values-sensitive domains
• Pluralistic moral frameworks (no hierarchy)
• Context-aware session management

Tractatus IS NOT: A governance system, ethical enforcement tool, or bad actor prevention mechanism

---

END OF ADR-001