diff --git a/docs/governance/AUTONOMOUS_DEVELOPMENT_RULES_PROPOSAL.md b/docs/governance/AUTONOMOUS_DEVELOPMENT_RULES_PROPOSAL.md deleted file mode 100644 index 83c34c5f..00000000 --- a/docs/governance/AUTONOMOUS_DEVELOPMENT_RULES_PROPOSAL.md +++ /dev/null @@ -1,856 +0,0 @@ -# Autonomous Development Rules - Proposal - -**Date**: 2025-10-20 -**Status**: PROPOSED (Awaiting user testing of Phase 2 work) -**Session**: Post-admin-UI-overhaul -**Purpose**: Enable autonomous resource management while ensuring quality - ---- - -## Context - -During the admin UI overhaul (Phase 1 + Phase 2), Claude Code demonstrated: -- Self-assessment of capacity before starting work -- Pragmatic scope adjustment (58% token reduction) -- Autonomous architectural decisions preserving UX -- Zero errors in deployment - -User question: "Would we be able to create a rule that allows you to self manage resources in this way while ensuring you avoid shortcuts that compromise quality?" - -This document proposes 8 new governance rules designed to exploit Tractatus framework capabilities for streamlined development with improved quality and reduced errors. - ---- - -## Proposed Rules Summary - -| ID | Category | Rule | Enforceability | Impact | -|----|----------|------|----------------|--------| -| inst_050 | Resource Mgmt | Mandatory Capacity Self-Assessment | HIGH | Prevents token exhaustion | -| inst_051 | Resource Mgmt | Progressive Token Checkpoint Reporting | HIGH | Automated pressure monitoring | -| inst_052 | Resource Mgmt | Scope Adjustment Authority | MEDIUM | Enables efficiency, requires trust | -| inst_053 | Quality | Architectural Decision Documentation | HIGH | Improves maintainability | -| inst_054 | Quality | Deployment Verification Chain | HIGH | Zero-defect deployments | -| inst_055 | Quality | Pragmatic Pattern Preservation | MEDIUM | Prevents over-refactoring | -| inst_056 | Error Prevention | Pattern Validation Before Batch Ops | MEDIUM | Prevents cascading errors | -| inst_057 | Error Prevention | Rollback Plan Documentation | HIGH | Risk mitigation | - ---- - -## Detailed Rule Specifications - -### inst_050: Mandatory Capacity Self-Assessment - -**Text**: "Before starting multi-file work (3+ files) or complex refactoring, perform explicit capacity self-assessment: estimate token cost, check current usage, calculate buffer, document decision to proceed/defer." - -**Quadrant**: OPERATIONAL -**Persistence**: HIGH -**Verification**: REQUIRED -**Explicitness**: 0.88 -**Temporal Scope**: PROJECT - -**Rationale**: This session's success came from explicit self-assessment before Phase 2: -- Estimated 62,000 tokens needed -- Checked 75,455 tokens remaining (62.3% used) -- Calculated 18% buffer -- Decided to PROCEED -- Actual usage: 26,000 tokens (58% under estimate) - -**Format for Assessment**: -```markdown -## Capacity Self-Assessment - -**Task**: [Description] -**Estimated Token Cost**: [Number] tokens -**Current Usage**: [Used] / [Budget] ([%] used) -**Remaining Budget**: [Number] tokens -**Buffer After Task**: [Number] tokens ([%]) -**Decision**: PROCEED / DEFER -**Rationale**: [Why this decision] -``` - -**Enforcement Hook**: -```javascript -// scripts/pre-action-check.js enhancement -if (action.type === 'multi_file_refactor' && action.file_count >= 3) { - const hasAssessment = checkRecentMessages(10).some(msg => - msg.includes('Capacity Self-Assessment') || - msg.includes('token cost') - ); - - if (!hasAssessment) { - return { - blocked: true, - rule: 'inst_050', - reason: 'Multi-file work requires capacity self-assessment', - suggestion: 'Document: estimated tokens, current usage, buffer, decision' - }; - } -} -``` - -**Testable Success Criteria**: -- βœ… PASS: Next session with 3+ file changes includes explicit capacity analysis -- ❌ FAIL: Session starts multi-file work without capacity check - ---- - -### inst_051: Progressive Token Checkpoint Reporting - -**Text**: "At 50k, 100k, 150k token milestones, run pressure check and report status. If pressure > ELEVATED at any checkpoint, create handoff summary before continuing." - -**Quadrant**: OPERATIONAL -**Persistence**: HIGH -**Verification**: REQUIRED -**Explicitness**: 0.92 -**Temporal Scope**: PROJECT - -**Rationale**: Automated checkpoints prevent gradual pressure accumulation. This session reached 33% usage (66k tokens) but never hit concerning levels because work was efficient. - -**Implementation** (enhance existing code in session-init.js): -```javascript -const TOKEN_CHECKPOINTS = [50000, 100000, 150000]; -let nextCheckpoint = TOKEN_CHECKPOINTS[0]; - -function checkTokenMilestone(tokensUsed) { - if (tokensUsed >= nextCheckpoint) { - console.log('\nπŸ”” Token Checkpoint Reached:', tokensUsed); - - // Run pressure check - const result = execSync( - `node scripts/check-session-pressure.js --tokens ${tokensUsed}/200000`, - { encoding: 'utf8' } - ); - - console.log(result); - - // Update next checkpoint - const idx = TOKEN_CHECKPOINTS.indexOf(nextCheckpoint); - nextCheckpoint = TOKEN_CHECKPOINTS[idx + 1] || Infinity; - - // Save state - updateSessionState({ last_checkpoint: tokensUsed, nextCheckpoint }); - } -} -``` - -**Testable Success Criteria**: -- βœ… PASS: Session exceeding 50k tokens shows checkpoint report -- ❌ FAIL: Session reaches 100k tokens without checkpoint reports - ---- - -### inst_052: Scope Adjustment Authority with Documentation - -**Text**: "Claude Code has authority to adjust implementation scope for efficiency when user grants 'full discretion', BUT must document rationale in commit message or handoff summary. Preserve user-valued patterns over forced uniformity." - -**Quadrant**: STRATEGIC -**Persistence**: HIGH -**Verification**: MANDATORY -**Explicitness**: 0.85 -**Temporal Scope**: PROJECT - -**Rationale**: Key efficiency driver this session - adjusted scope from "convert all 9 pages to unified component" to "convert 3 simple pages, standardize CSS for 6 complex pages". Result: 58% token savings, preserved valuable UX. - -**Boundary Conditions**: - -| Change Type | Original Scope | Adjusted Scope | Allowed? | Reason | -|-------------|----------------|----------------|----------|--------| -| UI Consistency | Force all pages into single component | Unified component for simple pages, standardize complex | βœ… YES | Preserves working patterns | -| Testing | Comprehensive test suite | Unit tests for critical paths | ❌ NO | Compromises quality | -| Security | Implement OAuth2 with PKCE | Use basic auth | ❌ NO | Changes security architecture (needs approval) | -| Performance | Optimize all queries | Optimize top 3 slow queries | βœ… YES | Pareto principle, measurable impact | -| Documentation | Full API docs for all endpoints | API docs for public endpoints | βœ… YES | Practical scope, incremental | - -**Documentation Template** (in commit message): -```markdown -SCOPE ADJUSTMENT: -Original: [Full scope description] -Adjusted: [Reduced scope description] - -RATIONALE: -- Token savings: ~[%] -- Preserves: [What functionality/patterns kept] -- Trade-off: [What deferred/omitted] -- User value: [Why adjustment maintains quality] -``` - -**Enforcement**: BoundaryEnforcer + Manual review - -**Testable Success Criteria**: -- βœ… PASS: "Full discretion" task shows scope trade-off documentation -- ❌ FAIL: Scope reduced without documented rationale - ---- - -### inst_053: Architectural Decision Documentation Standard - -**Text**: "When making architectural decisions (component patterns, data structures, API designs), document: (1) alternatives considered, (2) trade-offs, (3) rationale for choice. Include in commit message or create ADR (Architecture Decision Record) for major changes." - -**Quadrant**: STRATEGIC -**Persistence**: HIGH -**Verification**: MANDATORY -**Explicitness**: 0.90 -**Temporal Scope**: PROJECT - -**Rationale**: This session made architectural decision about navbar pattern: -- Alternative A: Single unified component for all pages -- Alternative B: Custom navbar for each page (status quo) -- Alternative C (SELECTED): Unified for simple, custom for complex - -Documented in commit message, but could be more structured. - -**ADR Format** (for major decisions): -```markdown -# ADR-[NUMBER]: [Title] - -**Date**: [YYYY-MM-DD] -**Status**: [Proposed | Accepted | Deprecated | Superseded] -**Deciders**: [Claude Code + User] - -## Context - -[What problem are we solving? What constraints exist?] - -## Decision Drivers - -- [Driver 1] -- [Driver 2] - -## Alternatives Considered - -### Option A: [Name] -**Description**: [Details] -**Pros**: -- [Pro 1] -- [Pro 2] -**Cons**: -- [Con 1] -- [Con 2] - -### Option B: [Name] -[Same format] - -### Option C: [Name] ⭐ SELECTED -[Same format] - -## Decision - -We chose Option C because [rationale]. - -## Consequences - -**Positive**: -- [Consequence 1] -- [Consequence 2] - -**Negative**: -- [Consequence 1] -- [Consequence 2] - -**Neutral**: -- [Consequence 1] -``` - -**When to Create ADR**: -- New component pattern affecting 3+ files -- Database schema changes -- API endpoint design -- Authentication/authorization changes -- State management patterns -- Deployment architecture changes - -**Enforcement**: -```javascript -// BoundaryEnforcer pattern detection -const architecturalPatterns = [ - /new.*component/i, - /schema.*change/i, - /api.*endpoint/i, - /authentication/i, - /state.*management/i -]; - -if (commitMessage.match(architecturalPatterns)) { - requireADROrDetailedRationale(); -} -``` - -**Testable Success Criteria**: -- βœ… PASS: Next architectural change includes ADR or detailed commit rationale -- ❌ FAIL: Component pattern changes without documented alternatives - ---- - -### inst_054: No Deployment Without Verification Chain - -**Text**: "Before deployment: (1) CSP compliance check [AUTOMATED], (2) Local server test on port 9000, (3) Commit with descriptive message, (4) Push to GitHub, (5) Deploy via rsync, (6) Verify service restart. Document each step completion." - -**Quadrant**: OPERATIONAL -**Persistence**: HIGH -**Verification**: MANDATORY -**Explicitness**: 0.95 -**Temporal Scope**: PROJECT - -**Rationale**: This session followed complete verification chain: -``` -βœ… CSP compliance check passed (post-commit hook) -βœ… Local server running (verified before deployment) -βœ… Committed: 75727bf with descriptive message -βœ… Pushed to GitHub: AgenticGovernance/tractatus -βœ… Deployed via rsync: 9 files transferred -βœ… Service restart: tractatus.service active (running) -``` - -**Verification Chain Checklist**: -```markdown -## Pre-Deployment Verification - -- [ ] 1. CSP Compliance: Run `npm run check:csp` OR rely on post-commit hook -- [ ] 2. Local Server: Verify `localhost:9000` responds correctly -- [ ] 3. Commit: Descriptive message following conventional commits format -- [ ] 4. Push: `git push origin main` succeeds -- [ ] 5. Deploy: `rsync` completes without errors -- [ ] 6. Restart: Service status shows "active (running)" -- [ ] 7. Smoke Test: Visit production URL, verify key functionality - -## Rollback Info - -- Last known good commit: [SHA] -- Rollback command: `git revert [SHA] && ./deploy.sh` -``` - -**Enforcement in Deploy Script**: -```bash -#!/bin/bash - -echo "πŸ” PRE-DEPLOYMENT VERIFICATION CHAIN" - -# 1. Check CSP -echo "[1/6] CSP Compliance..." -npm run check:csp || { echo "❌ CSP check failed"; exit 1; } - -# 2. Check local server -echo "[2/6] Local Server Status..." -curl -s http://localhost:9000 > /dev/null || { echo "❌ Local server not responding"; exit 1; } - -# 3. Check git status -echo "[3/6] Git Status..." -[[ $(git status --porcelain) ]] && { echo "❌ Uncommitted changes"; exit 1; } - -# 4. Push to GitHub -echo "[4/6] Pushing to GitHub..." -git push origin main || { echo "❌ Push failed"; exit 1; } - -# 5. Deploy -echo "[5/6] Deploying to production..." -rsync -avz --exclude-from='.rsyncignore' ... || { echo "❌ Deploy failed"; exit 1; } - -# 6. Verify service -echo "[6/6] Verifying service..." -ssh ... "systemctl status tractatus" | grep "active (running)" || { echo "❌ Service not active"; exit 1; } - -echo "βœ… DEPLOYMENT SUCCESSFUL" -``` - -**Testable Success Criteria**: -- βœ… PASS: Next deployment shows all 6 verification steps in output -- ❌ FAIL: Deployment skips steps or fails verification - ---- - -### inst_055: Pragmatic Pattern Preservation Over Forced Uniformity - -**Text**: "When refactoring, preserve working patterns that serve legitimate use cases, even if they don't match ideal architecture. Standardize appearance/conventions, but don't force-fit different use cases into single component. Document why patterns differ." - -**Quadrant**: STRATEGIC -**Persistence**: HIGH -**Verification**: REQUIRED -**Explicitness**: 0.82 -**Temporal Scope**: PROJECT - -**Rationale**: Critical insight from this session: -- media-triage.html has cross-page navigation: Dashboard | Blog | Media | Projects | Audit -- rule-manager.html has cross-page navigation: Dashboard | Rules | Blog | Audit -- These tabs serve legitimate UX need: quick switching between related admin sections -- Forcing unified navbar component would break this functionality -- Better solution: Standardize CSS versioning, keep custom navbars - -**Decision Framework**: - -| Question | Answer | Action | -|----------|--------|--------| -| Does pattern serve legitimate use case? | YES | Preserve pattern | -| Can pattern be standardized without breaking functionality? | YES | Standardize appearance | -| Would forced uniformity reduce usability? | YES | Keep pattern, document | -| Is pattern causing bugs/maintenance issues? | NO | Low priority for refactor | - -**Pattern Categories**: - -1. **Navigation Patterns** - - Simple navbar (blog post pages, documentation) β†’ Unified component βœ… - - Cross-page navigation (admin workflows) β†’ Custom navbar βœ… - - Internal tabs (settings pages) β†’ Custom tabs βœ… - -2. **Data Structures** - - Similar entities (User, Admin) β†’ Shared schema βœ… - - Different purposes (BlogPost vs CaseStudy) β†’ Separate schemas βœ… - -3. **API Endpoints** - - CRUD operations β†’ RESTful pattern βœ… - - Complex workflows (multi-step forms) β†’ Custom endpoints βœ… - -**Documentation Template**: -```markdown -## Pattern Preservation Decision - -**Pattern**: [Description of non-standard pattern] -**Location**: [Files/components] - -**Use Case**: [Why this pattern exists] -**Alternatives Considered**: -1. [Alternative 1] - Rejected because [reason] -2. [Alternative 2] - Rejected because [reason] - -**Decision**: Preserve pattern because [rationale] -**Standardization Applied**: [What was standardized instead] -``` - -**Testable Success Criteria**: -- βœ… PASS: Refactoring preserves functional patterns with documentation -- ❌ FAIL: All pages forced into single pattern breaking functionality - ---- - -### inst_056: Pattern Validation Before Batch Operations - -**Text**: "When performing batch operations (editing 3+ similar files), validate pattern on 1 file first, verify success, then apply to remaining files. Document pattern in commit message." - -**Quadrant**: OPERATIONAL -**Persistence**: HIGH -**Verification**: REQUIRED -**Explicitness**: 0.90 -**Temporal Scope**: PROJECT - -**Rationale**: This session followed incremental approach: -1. Updated newsletter-management.html first (2 lines: unified navbar component) -2. Verified component loaded correctly -3. Applied same pattern to hooks-dashboard.html -4. Applied to audit-analytics.html (also fixed wrong navbar) -Result: Zero errors, clean deployment - -**Batch Operation Protocol**: - -```markdown -## Batch Operation: [Description] - -**Files Affected**: [Count] files -**Pattern**: [What change is being made] - -### Validation Phase -1. Applied pattern to: [first file] -2. Verification: [How success was confirmed] -3. Result: βœ… PASS / ❌ FAIL - -### Batch Application Phase -[If validation passed] -4. Applied to remaining files: [list] -5. Final verification: [How batch success confirmed] -``` - -**Example from this session**: -```markdown -## Batch Operation: Unified Navbar Component - -**Files Affected**: 3 files -**Pattern**: Replace custom navbar HTML with: -```html -
- -``` - -### Validation Phase -1. Applied pattern to: newsletter-management.html -2. Verification: Loaded localhost:9000/admin/newsletter-management.html -3. Result: βœ… PASS (navbar renders, logout works, admin name displays) - -### Batch Application Phase -4. Applied to: hooks-dashboard.html, audit-analytics.html -5. Final verification: All pages load, consistent styling -``` - -**Enforcement Warning**: -```javascript -// Hook validator detects batch edit pattern -if (filesBeingEdited.length >= 3 && similarPattern(filesBeingEdited)) { - logWarning({ - rule: 'inst_056', - message: 'Batch operation detected', - suggestion: 'Consider validating pattern on one file first', - filesAffected: filesBeingEdited.length - }); -} -``` - -**Testable Success Criteria**: -- βœ… PASS: Next 3+ file batch edit shows incremental validation approach -- ❌ FAIL: All files edited simultaneously without validation step - ---- - -### inst_057: Rollback Plan Documentation for Risky Changes - -**Text**: "For changes affecting: (1) production database schemas, (2) authentication/security, (3) critical user workflows, document rollback plan BEFORE making changes. Include: backup steps, reversion commands, verification tests." - -**Quadrant**: OPERATIONAL -**Persistence**: HIGH -**Verification**: MANDATORY -**Explicitness**: 0.92 -**Temporal Scope**: PROJECT - -**Rationale**: Phase 1 fixed authentication bugs (localStorage key mismatches). Low risk because local testing available, but higher-risk changes need documented rollback plans. - -**Risk Assessment Matrix**: - -| Change Type | Risk Level | Rollback Required? | Backup Required? | -|-------------|------------|-------------------|------------------| -| CSS/styling changes | LOW | No | No | -| Component refactoring | LOW-MEDIUM | Suggested | No | -| localStorage key changes | MEDIUM | YES | No (client-side) | -| Database schema changes | HIGH | YES | YES (db dump) | -| Authentication changes | HIGH | YES | YES (config + db) | -| API endpoint changes | MEDIUM-HIGH | YES | Depends | -| Payment processing | CRITICAL | YES | YES + test plan | - -**Rollback Plan Template**: - -```markdown -# Rollback Plan: [Change Description] - -**Date**: [YYYY-MM-DD] -**Risk Level**: [LOW | MEDIUM | HIGH | CRITICAL] -**Estimated Rollback Time**: [minutes] - -## Change Summary -[What is being changed and why] - -## Risk Assessment -- **Data Loss Potential**: [YES/NO - details] -- **Service Downtime**: [YES/NO - estimated duration] -- **User Impact**: [Description] - -## Pre-Change Backup - -### Database Backup (if applicable) -```bash -# Backup commands -mongodump --db tractatus_dev --out /backups/pre-[change-id]-$(date +%Y%m%d-%H%M%S) -``` - -### Configuration Backup -```bash -# Config backup commands -cp .env .env.backup-[change-id] -``` - -### Code Backup -```bash -# Git commit SHA before changes -BACKUP_COMMIT=$(git rev-parse HEAD) -echo $BACKUP_COMMIT > .rollback-point -``` - -## Rollback Procedure - -### Step 1: Stop Service -```bash -sudo systemctl stop tractatus -``` - -### Step 2: Restore Code -```bash -git reset --hard $(cat .rollback-point) -``` - -### Step 3: Restore Database (if needed) -```bash -mongorestore --db tractatus_dev /backups/pre-[change-id]-[timestamp] -``` - -### Step 4: Restore Configuration -```bash -cp .env.backup-[change-id] .env -``` - -### Step 5: Restart Service -```bash -sudo systemctl start tractatus -``` - -## Verification Tests - -After rollback, verify: -- [ ] Service status: `systemctl status tractatus` shows "active (running)" -- [ ] Homepage loads: `curl https://agenticgovernance.digital` -- [ ] Admin login works: Test with admin credentials -- [ ] [Specific feature] works: [Verification steps] - -## Success Criteria - -Rollback is successful when: -1. All verification tests pass -2. No error logs in `/var/log/tractatus/error.log` -3. User workflows function as before change - -## Point of Contact - -**Person**: [Name or "On-call admin"] -**Notification**: [How to notify if rollback needed] -``` - -**Example - Database Schema Change**: -```markdown -# Rollback Plan: Add "verified_at" Field to Newsletter Subscriptions - -**Risk Level**: MEDIUM -**Estimated Rollback Time**: 5 minutes - -## Change Summary -Adding `verified_at` timestamp field to newsletter_subscriptions collection. - -## Risk Assessment -- **Data Loss Potential**: NO - additive change only -- **Service Downtime**: NO - backwards compatible -- **User Impact**: None (new field, existing records get null) - -## Pre-Change Backup -```bash -mongodump --db tractatus_dev --collection newsletter_subscriptions \ - --out /backups/pre-newsletter-schema-20251020 -``` - -## Rollback Procedure - -### If Migration Fails Mid-Process -```bash -# Drop the new field -mongosh tractatus_dev -db.newsletter_subscriptions.updateMany({}, { $unset: { verified_at: "" } }) -``` - -### If Need Full Rollback -```bash -# Restore from backup -mongorestore --db tractatus_dev --collection newsletter_subscriptions \ - /backups/pre-newsletter-schema-20251020/tractatus_dev/newsletter_subscriptions.bson -``` - -## Verification Tests -- [ ] Collection schema: `db.newsletter_subscriptions.findOne()` shows expected fields -- [ ] Subscription count unchanged: `db.newsletter_subscriptions.countDocuments()` -- [ ] Admin newsletter page loads: https://agenticgovernance.digital/admin/newsletter-management.html -``` - -**Enforcement**: -```javascript -// BoundaryEnforcer checks -const riskyPatterns = [ - /schema.*change/i, - /database.*migration/i, - /authentication/i, - /security/i, - /payment/i -]; - -if (description.match(riskyPatterns) && !hasRollbackPlan()) { - return { - blocked: true, - rule: 'inst_057', - reason: 'High-risk change requires documented rollback plan', - template: 'See docs/governance/AUTONOMOUS_DEVELOPMENT_RULES_PROPOSAL.md' - }; -} -``` - -**Testable Success Criteria**: -- βœ… PASS: Next database schema change includes rollback plan before execution -- ❌ FAIL: High-risk change proceeds without rollback documentation - ---- - -## Implementation Roadmap - -### Phase 1: Immediate (Next Session) -- βœ… inst_050: Capacity Self-Assessment (manual enforcement) -- βœ… inst_052: Scope Adjustment Authority (manual, test with next "full discretion" task) -- βœ… inst_056: Pattern Validation (manual, observe in next batch operation) - -### Phase 2: Automated Enforcement (Within 2 Sessions) -- πŸ”§ inst_051: Token Checkpoints (enhance session-init.js) -- πŸ”§ inst_054: Deployment Verification Chain (enhance deploy script) - -### Phase 3: Advanced (Within 5 Sessions) -- πŸ”§ inst_053: ADR Enforcement (BoundaryEnforcer pattern detection) -- πŸ”§ inst_055: Pattern Preservation Detection (CrossReferenceValidator) -- πŸ”§ inst_057: Rollback Plan Enforcement (BoundaryEnforcer risk assessment) - ---- - -## Testing Plan - -### Session N+1 (Immediate Next Session) -**Test Scenario**: Multi-file refactoring task - -**Expected Behaviors**: -1. Claude performs capacity self-assessment before starting (inst_050) -2. If given "full discretion", documents scope trade-offs (inst_052) -3. Validates pattern on one file before batch application (inst_056) -4. Documents architectural decisions in commit (inst_053) - -**Success Metrics**: -- βœ… Capacity assessment documented: YES/NO -- βœ… Scope trade-offs documented (if applicable): YES/NO -- βœ… Incremental validation approach: YES/NO -- βœ… Clear commit messages: YES/NO - -### Session N+2 (After Automation) -**Test Scenario**: Database schema change + deployment - -**Expected Behaviors**: -1. Token checkpoint reports at 50k milestone (inst_051) -2. Rollback plan created before schema change (inst_057) -3. Full verification chain in deployment (inst_054) -4. ADR created for schema design (inst_053) - -**Success Metrics**: -- βœ… Checkpoint report shown: YES/NO -- βœ… Rollback plan documented: YES/NO -- βœ… All 6 deployment steps verified: YES/NO -- βœ… ADR created: YES/NO - ---- - -## Expected Impact - -### Efficiency Gains -- **Token Reduction**: 30-50% through better scope management and parallel operations -- **Time Reduction**: Faster deployments through automated verification chains -- **Error Prevention**: 80% reduction in cascading errors through pattern validation - -### Quality Improvements -- **Documentation**: Complete architectural context for future sessions -- **Maintainability**: Preserved patterns documented, not mystifying -- **Reliability**: Rollback plans reduce deployment anxiety - -### Risk Mitigation -- **Token Exhaustion**: Early warning system via checkpoints -- **Production Incidents**: Rollback plans enable rapid recovery -- **Technical Debt**: Pragmatic pattern preservation prevents forced refactors - ---- - -## Questions for User Review - -1. **Authority Boundaries**: inst_052 grants scope adjustment authority with "full discretion". Are there categories of changes that should NEVER be adjusted without explicit approval? - -2. **Documentation Overhead**: ADRs (inst_053) add upfront documentation cost. Should this only apply to changes affecting 5+ files, or keep at current threshold? - -3. **Risk Assessment**: inst_057 requires rollback plans for HIGH risk changes. Should MEDIUM risk changes also require rollback plans, or just suggested? - -4. **Enforcement Priority**: Which rules should have automated enforcement first? Current plan: inst_051 β†’ inst_054 β†’ inst_053 β†’ inst_057 - -5. **Testing Criteria**: Should there be a "certification" process where these rules are tested across 3-5 sessions before being added to .claude/instruction-history.json permanently? - ---- - -## Appendices - -### Appendix A: Comparison to inst_049 (Test User Hypothesis First) - -**inst_049**: "When user suggests technical hypothesis, test it BEFORE pursuing alternatives" -**Difference**: inst_049 is about respecting user input. inst_052-058 are about autonomous efficiency with quality safeguards. - -**Relationship**: These rules complement each other: -- inst_049: User says "Maybe it's a Tailwind issue" β†’ Test that first -- inst_052: User says "Fix all admin pages" + "full discretion" β†’ Adjust scope pragmatically -- inst_050: Before starting either β†’ Assess capacity - -### Appendix B: Framework Component Alignment - -| Rule | Framework Component | Relationship | -|------|-------------------|--------------| -| inst_050 | ContextPressureMonitor | Leverages pressure scoring | -| inst_051 | ContextPressureMonitor | Automated checkpoint integration | -| inst_052 | BoundaryEnforcer | Authority boundaries | -| inst_053 | CrossReferenceValidator | Decision documentation | -| inst_054 | BoundaryEnforcer | Deployment safety | -| inst_055 | PluralisticDeliberationOrchestrator | Pattern preservation reasoning | -| inst_056 | MetacognitiveVerifier | Incremental validation | -| inst_057 | BoundaryEnforcer | Risk mitigation | - -### Appendix C: Token Efficiency Analysis - -**This Session (With Proto-Rules)**: -- Initial estimate: 62,000 tokens -- Actual usage: 26,000 tokens (58% reduction) -- Key efficiency factors: - - Pragmatic scope adjustment (inst_052) - - Pattern validation approach (inst_056) - - Parallel operations (4 CSS edits simultaneously) - -**Projected Future Sessions (With Full Rules)**: -- Baseline efficiency: +30% (self-assessment prevents over-commitment) -- Automation efficiency: +20% (checkpoints prevent pressure creep) -- Documentation overhead: -10% (ADRs take time upfront) -- Net improvement: +40% efficiency with +95% quality retention - ---- - -**End of Proposal** - -**Next Steps**: -1. User tests Phase 2 admin UI work (validation of current quality) -2. User reviews this proposal and provides feedback -3. If approved, implement inst_050, inst_052, inst_056 manually in next session -4. After 2-3 session validation, automate inst_051, inst_054 -5. After 5 sessions, add to .claude/instruction-history.json permanently - -**Document Status**: AWAITING USER REVIEW - ---- - -## USER FEEDBACK & APPROVAL (2025-10-20) βœ… - -### Questions Answered - -1. **Authority Boundaries**: βœ… YES - NEVER adjust scope without approval for: - - Security architecture changes - - User credentials - - Media responses - - Any third-party interactions (except pre-approved: GitHub, OVHCloud) - -2. **Documentation Overhead**: βœ… At Claude's discretion - situations vary, decide in context - -3. **Risk Assessment**: βœ… At Claude's discretion - situations vary, decide in context - -4. **Enforcement Priority**: βœ… Proceed at full discretion - -5. **Testing Criteria**: βœ… Proceed at full discretion - -### Final Status - -**βœ… APPROVED**: All 8 rules added to `.claude/instruction-history.json` - -**Rule IDs**: inst_050 through inst_057 -**Total Instructions**: 48 (was 40) -**Date Established**: 2025-10-20T21:16:23Z -**Session**: 2025-10-20-autonomous-rules - -**Next Steps**: -- Rules active immediately -- Manual enforcement in next session -- Automated enforcement to be implemented progressively -- Effectiveness to be evaluated after 3-5 sessions - ---- - -**Document Status**: APPROVED & IMPLEMENTED diff --git a/docs/governance/CODING_BEST_PRACTICES_SUMMARY.md b/docs/governance/CODING_BEST_PRACTICES_SUMMARY.md deleted file mode 100644 index d1abf46b..00000000 --- a/docs/governance/CODING_BEST_PRACTICES_SUMMARY.md +++ /dev/null @@ -1,418 +0,0 @@ -# Coding Best Practices - Governance Rules Summary - -**Created**: 2025-10-11 -**Context**: Lessons learned from Phase 2 Migration API validation error -**Analysis Document**: `docs/analysis/PHASE_2_ERROR_ANALYSIS.md` - ---- - -## Overview - -Following the Phase 2 migration API validation error (`source: 'claude_md_migration' is not a valid enum value`), a comprehensive root cause analysis was conducted. This analysis identified **5 major categories of preventable errors**: - -1. **Schema-Code Mismatch** - Controller code not aligned with database schema -2. **Magic Strings** - Hardcoded string literals instead of constants -3. **Development Environment Cache** - Stale model definitions after schema changes -4. **Insufficient Testing** - No integration tests before declaring code complete -5. **Documentation Gaps** - Enum values not centrally documented - -Based on this analysis, **10 governance rules** were created to prevent similar errors in future development. - ---- - -## Created Governance Rules - -### 1. **inst_021** - Centralized Constants for Enums -**Quadrant**: SYSTEM | **Persistence**: HIGH | **Priority**: 95 - -``` -ALL database enum values MUST be defined in a centralized constants file -(src/constants/*.constants.js). Controllers and services MUST import constants, -NEVER use string literals for enum values. -``` - -**Examples**: -- βœ… GOOD: `source: GOVERNANCE_SOURCES.CLAUDE_MD_MIGRATION` -- ❌ BAD: `source: 'claude_md_migration'` - -**Prevents**: Schema-code mismatches, typos, refactoring errors - ---- - -### 2. **inst_022** - Pre-Save Validation -**Quadrant**: TACTICAL | **Persistence**: HIGH | **Priority**: 90 - -``` -BEFORE saving any Mongoose model instance, code MUST validate enum field values -against the schema's allowed values. Use pre-save validation or explicit checks. -``` - -**Examples**: -- βœ… GOOD: `if (!ENUM_VALUES.includes(value)) throw new Error(...)` -- ❌ BAD: Directly calling `newModel.save()` without validation - -**Prevents**: Runtime database validation errors, silent failures - ---- - -### 3. **inst_023** - JSDoc Type Annotations -**Quadrant**: TACTICAL | **Persistence**: HIGH | **Priority**: 85 - -``` -ALL functions that create or update database models MUST include JSDoc type -annotations specifying allowed enum values. Use @typedef for complex types. -``` - -**Examples**: -- βœ… GOOD: `@property {'user_instruction'|'framework_default'|'claude_md_migration'} source` -- ❌ BAD: `@property {string} source` (too vague) - -**Prevents**: IDE type checking catches enum mismatches at dev-time - ---- - -### 4. **inst_024** - Server Restart After Model Changes -**Quadrant**: OPERATIONAL | **Persistence**: HIGH | **Priority**: 80 - -``` -AFTER modifying any Mongoose model schema (*.model.js files), developer MUST -restart the Node.js server to clear require() cache. Use nodemon for automatic restarts. -``` - -**Examples**: -- βœ… GOOD: `npm run dev` (uses nodemon, auto-restarts) -- ❌ BAD: Editing model and testing without restart - -**Prevents**: Testing against stale cached models - ---- - -### 5. **inst_025** - Constants File Structure -**Quadrant**: TACTICAL | **Persistence**: HIGH | **Priority**: 85 - -``` -WHEN creating constants files for enums, MUST export both: -(1) Named object with constants (e.g., GOVERNANCE_SOURCES), -(2) Array of values (e.g., GOVERNANCE_SOURCE_VALUES). -Array MUST be used in model schema enum definition. -``` - -**Examples**: -- βœ… GOOD: `module.exports = { GOVERNANCE_SOURCES, GOVERNANCE_SOURCE_VALUES }` -- βœ… GOOD: Model uses `enum: GOVERNANCE_SOURCE_VALUES` - -**Prevents**: Duplication of enum definitions - ---- - -### 6. **inst_026** - Clear Validation Error Messages -**Quadrant**: TACTICAL | **Persistence**: MEDIUM | **Priority**: 70 - -``` -ALL validation errors from Mongoose MUST include the invalid value and list of -valid values in the error message. Use custom error messages with {VALUES} placeholder. -``` - -**Examples**: -- βœ… GOOD: `enum: { values: [...], message: '{VALUE} not valid. Must be: {VALUES}' }` -- ❌ BAD: Generic "Validation failed" with no context - -**Prevents**: Lengthy debugging sessions, unclear errors - ---- - -### 7. **inst_027** - Integration Tests Before Completion -**Quadrant**: OPERATIONAL | **Persistence**: HIGH | **Priority**: 90 - -``` -ALL new API endpoints MUST have integration tests that hit the real database -BEFORE marking the implementation complete. Test MUST include both success and failure cases. -``` - -**Examples**: -- βœ… GOOD: `tests/integration/migration.test.js` with database operations -- ❌ BAD: Marking API complete without integration tests - -**Prevents**: Production deployment of broken code - ---- - -### 8. **inst_028** - Schema Change Checklist -**Quadrant**: OPERATIONAL | **Persistence**: HIGH | **Priority**: 95 - -``` -WHEN adding or modifying database schema enum fields, developer MUST: -(1) Update/create constants file, -(2) Update model to use constants, -(3) Write validation tests, -(4) Follow Schema Change Checklist in docs/developer/SCHEMA_CHANGE_CHECKLIST.md -``` - -**Examples**: -- βœ… GOOD: Updated constants, model, wrote tests -- ❌ BAD: Updated code without writing tests - -**Prevents**: Forgotten steps in schema changes - ---- - -### 9. **inst_029** - Enum Documentation -**Quadrant**: OPERATIONAL | **Persistence**: MEDIUM | **Priority**: 75 - -``` -ALL enum value additions or changes MUST be documented in docs/developer/ENUM_VALUES.md -with table showing value, constant name, and description. Include instructions for adding new values. -``` - -**Examples**: -- βœ… GOOD: Updated ENUM_VALUES.md table when adding `claude_md_migration` -- ❌ BAD: Adding enum value without documentation - -**Prevents**: Developers inventing new values without checking existing ones - ---- - -### 10. **inst_030** - Test Before Declaring Complete -**Quadrant**: OPERATIONAL | **Persistence**: HIGH | **Priority**: 90 - -``` -BEFORE declaring any code implementation 'complete', developer MUST run all relevant tests -and verify they pass. For database code, this MUST include integration tests with real database operations. -``` - -**Examples**: -- βœ… GOOD: `npm test && curl POST /api/endpoint` (verify works) -- ❌ BAD: Writing code and marking complete without testing - -**Prevents**: Discovering errors during final testing phase instead of immediately - ---- - -## Rule Categories by Quadrant - -### SYSTEM (1 rule) -- **inst_021**: Centralized constants for enums - -### TACTICAL (4 rules) -- **inst_022**: Pre-save validation -- **inst_023**: JSDoc type annotations -- **inst_025**: Constants file structure -- **inst_026**: Clear validation error messages - -### OPERATIONAL (5 rules) -- **inst_024**: Server restart after model changes -- **inst_027**: Integration tests before completion -- **inst_028**: Schema change checklist -- **inst_029**: Enum documentation -- **inst_030**: Test before declaring complete - ---- - -## Rule Categories by Persistence - -### HIGH (8 rules) -- inst_021, inst_022, inst_023, inst_024, inst_025, inst_027, inst_028, inst_030 - -### MEDIUM (2 rules) -- inst_026, inst_029 - ---- - -## Implementation Checklist - -When implementing these rules in a new project: - -### Phase 1: File Structure Setup -- [ ] Create `src/constants/` directory -- [ ] Create constants files for all enum types -- [ ] Export both named object and values array -- [ ] Update models to import constants - -### Phase 2: Code Quality -- [ ] Add JSDoc annotations to all database functions -- [ ] Add pre-save validation for enum fields -- [ ] Update error messages with {VALUES} placeholder - -### Phase 3: Development Environment -- [ ] Install nodemon: `npm install --save-dev nodemon` -- [ ] Add dev script: `"dev": "nodemon src/server.js"` -- [ ] Document restart requirements in README - -### Phase 4: Testing -- [ ] Write integration tests for all API endpoints -- [ ] Test success and failure cases -- [ ] Add test-before-complete to workflow - -### Phase 5: Documentation -- [ ] Create `docs/developer/ENUM_VALUES.md` -- [ ] Create `docs/developer/SCHEMA_CHANGE_CHECKLIST.md` -- [ ] Document all enum values with tables -- [ ] Add "To Add New Value" instructions - ---- - -## Real-World Application - -### Example: Adding New Enum Value - -**Scenario**: Need to add new source type `'api_import'` for rules imported from external API - -**Following the Rules**: - -1. **inst_021** - Update constants file: -```javascript -// src/constants/governance.constants.js -const GOVERNANCE_SOURCES = { - USER_INSTRUCTION: 'user_instruction', - FRAMEWORK_DEFAULT: 'framework_default', - AUTOMATED: 'automated', - MIGRATION: 'migration', - CLAUDE_MD_MIGRATION: 'claude_md_migration', - API_IMPORT: 'api_import', // βœ… NEW - TEST: 'test' -}; -``` - -2. **inst_028** - Follow checklist: -- βœ… Updated constants file -- βœ… Model already uses `GOVERNANCE_SOURCE_VALUES` (auto-includes new value) -- βœ… Write validation test - -3. **inst_023** - Update JSDoc: -```javascript -/** - * @property {'user_instruction'|'framework_default'|'automated'|'migration'|'claude_md_migration'|'api_import'|'test'} source - */ -``` - -4. **inst_027** - Write integration test: -```javascript -it('should create rule with api_import source', async () => { - const rule = new GovernanceRule({ - source: GOVERNANCE_SOURCES.API_IMPORT // βœ… Using constant - }); - await expect(rule.save()).resolves.not.toThrow(); -}); -``` - -5. **inst_029** - Update documentation: -```markdown -| `api_import` | `GOVERNANCE_SOURCES.API_IMPORT` | Imported from external API | -``` - -6. **inst_024** - Restart server: -```bash -npm run dev # Nodemon auto-restarts -``` - -7. **inst_030** - Test before declaring complete: -```bash -npm test # All tests pass -curl POST /api/endpoint # Verify endpoint works -``` - -**Result**: New enum value added safely with zero errors! πŸŽ‰ - ---- - -## Prevention Effectiveness - -### Time Comparison - -**Without These Rules** (Phase 2 actual experience): -- Writing code: 15 minutes -- Testing and discovering error: 5 minutes -- Debugging root cause: 15 minutes -- Fixing model: 2 minutes -- Discovering server cache issue: 10 minutes -- Restarting and re-testing: 3 minutes -- **Total: ~50 minutes** - -**With These Rules** (estimated): -- Writing code with constants: 15 minutes -- Writing JSDoc annotations: 5 minutes -- Writing integration test: 10 minutes -- Running test (catches error immediately): 1 minute -- **Total: ~31 minutes** - -**Time Saved**: 19 minutes per incident -**Error Rate**: Near zero (caught by tests before deployment) - ---- - -## Error Prevention Matrix - -| Error Type | Prevented By | How | -|------------|--------------|-----| -| **Schema-Code Mismatch** | inst_021, inst_022, inst_025 | Constants + validation | -| **Magic Strings** | inst_021, inst_023 | Centralized constants + types | -| **Stale Cache** | inst_024 | Auto-restart with nodemon | -| **Missing Tests** | inst_027, inst_030 | Required integration tests | -| **Unclear Errors** | inst_026 | Descriptive error messages | -| **Forgotten Steps** | inst_028 | Schema change checklist | -| **Undocumented Enums** | inst_029 | Mandatory documentation | - ---- - -## Metrics & Monitoring - -### Compliance Checks - -**Automated (CI/CD Pipeline)**: -```bash -# Check for magic strings in controllers -grep -r "'user_instruction'" src/controllers/ && exit 1 - -# Verify constants files exist -test -f src/constants/governance.constants.js || exit 1 - -# Check JSDoc coverage -npm run check-jsdoc || exit 1 - -# Run integration tests -npm run test:integration || exit 1 -``` - -**Manual Code Review**: -- [ ] All new enum values have constants -- [ ] All database functions have JSDoc -- [ ] All API endpoints have integration tests -- [ ] ENUM_VALUES.md updated - ---- - -## Success Criteria - -These rules are successful when: - -1. βœ… Zero schema-code mismatch errors in production -2. βœ… All enum values defined in constants files -3. βœ… 100% integration test coverage for API endpoints -4. βœ… All database errors include helpful context -5. βœ… Developer onboarding time reduced (clear documentation) -6. βœ… Code review time reduced (self-checking code) - ---- - -## Related Documents - -- **Root Cause Analysis**: `docs/analysis/PHASE_2_ERROR_ANALYSIS.md` -- **Phase 2 Test Results**: `docs/testing/PHASE_2_TEST_RESULTS.md` -- **Schema Change Checklist**: `docs/developer/SCHEMA_CHANGE_CHECKLIST.md` (to be created) -- **Enum Values Reference**: `docs/developer/ENUM_VALUES.md` (to be created) - ---- - -## Conclusion - -The Phase 2 migration API error was a **blessing in disguise**. It revealed systemic weaknesses in development practices that, if left unchecked, would have caused repeated errors. - -By creating these 10 governance rules, we've transformed a debugging session into a **permanent improvement** to code quality and developer experience. - -**Prevention is cheaper than debugging.** - ---- - -**Created By**: Claude Code Assistant -**Date**: 2025-10-11 -**Status**: βœ… Active - All 10 rules enforced in tractatus_dev database diff --git a/docs/governance/MONTHLY-REVIEW-SCHEDULE.md b/docs/governance/MONTHLY-REVIEW-SCHEDULE.md deleted file mode 100644 index efa4be8b..00000000 --- a/docs/governance/MONTHLY-REVIEW-SCHEDULE.md +++ /dev/null @@ -1,98 +0,0 @@ -# Monthly Review Schedule - Tractatus Governance - -**Document Type:** Operational Schedule -**Created:** 2025-10-11 -**Last Updated:** 2025-10-11 -**Owner:** Human PM (John Stroh) - ---- - -## Purpose - -This document tracks strategic decisions, reviews, and reminders that require human PM attention on a monthly or scheduled basis. All items are organized by review month. - ---- - -## November 2025 - -### Strategic Decisions Deferred - -**1. Privacy-Preserving Analytics Implementation** -- **Document:** `docs/governance/PRIVACY-PRESERVING-ANALYTICS-PLAN.md` -- **Issue:** Privacy policy claims analytics exist but implementation missing -- **Options:** - - Option A: Remove analytics claims from privacy policy (no implementation) - - Option B: Implement Plausible Analytics (privacy-first, $9/month) -- **Decision Required:** Choose analytics approach (values-sensitive) -- **Deferred Date:** 2025-10-11 -- **Priority:** CRITICAL (Values alignment) -- **Status:** DEFERRED - ---- - -## December 2025 - -*(No scheduled reviews yet)* - ---- - -## January 2026 - -*(No scheduled reviews yet)* - ---- - -## Annual Reviews - -### October 2026 - -**1. Core Values and Principles - Annual Review** -- **Document:** `docs/governance/TRA-VAL-0001-core-values-principles-v1-0.md` -- **Scheduled Date:** 2026-10-06 (one year from creation) -- **Scope:** Comprehensive evaluation of values relevance and implementation -- **Authority:** Human PM with community input -- **Outcome:** Updated version or reaffirmation of current values - ---- - -## Recurring Monthly Checks - -### Framework Health Metrics (Monthly) -- [ ] Review audit logs for boundary violations -- [ ] Check framework component activity rates -- [ ] Assess instruction history growth patterns -- [ ] Monitor pressure checkpoints and session failures - -### Community Engagement (Monthly) -- [ ] Review media inquiry queue -- [ ] Process case study submissions -- [ ] Check blog post suggestions (AI-curated, human-approved) - -### Security & Privacy (Monthly) -- [ ] Review server logs for suspicious activity (90-day retention) -- [ ] Verify HTTPS certificate renewals -- [ ] Check backup integrity -- [ ] Audit admin access logs - ---- - -## Adding New Reminders - -To add a new scheduled review: - -1. Determine review month -2. Add entry under appropriate section -3. Include: Document reference, decision required, priority, status -4. Update "Last Updated" date at top of document - ---- - -## Completed Reviews - -*(Completed reviews will be moved here with completion date and outcome)* - ---- - -**Next Review of This Document:** 2025-11-01 (monthly) - -*This document is maintained as part of Tractatus governance framework operational procedures.* diff --git a/docs/governance/PRIVACY-PRESERVING-ANALYTICS-PLAN.md b/docs/governance/PRIVACY-PRESERVING-ANALYTICS-PLAN.md deleted file mode 100644 index eec973d9..00000000 --- a/docs/governance/PRIVACY-PRESERVING-ANALYTICS-PLAN.md +++ /dev/null @@ -1,308 +0,0 @@ -# Privacy-Preserving Analytics Implementation Plan - -**Document Type:** Implementation Plan -**Created:** 2025-10-11 -**Author:** Claude (Session 2025-10-07-001) -**Priority:** CRITICAL (Values alignment) -**Status:** DEFERRED - Scheduled for review November 2025 -**Decision:** Deferred by Human PM (John Stroh) on 2025-10-11 - -**Related Documents:** TRA-VAL-0001 (Core Values), privacy.html -**Primary Quadrant:** STRATEGIC (Values-sensitive decision) - ---- - -## Executive Summary - -**Problem Identified:** The Tractatus privacy policy claims "privacy-respecting analytics (no cross-site tracking)" but NO analytics implementation currently exists. This creates a gap between stated policy and actual implementation. - -**Values Consideration:** Per TRA-VAL-0001, our core value is "Privacy-First Design: No tracking, no surveillance, minimal data collection." This is a **values-sensitive decision requiring human approval**. - -**Recommended Solution:** Implement Plausible Analytics (cloud-hosted initially, self-hosted in Phase 2) as a privacy-preserving analytics solution that aligns with our core values. - ---- - -## Current State Analysis - -### What Was Discovered (October 11, 2025) - -1. **No Analytics Implementation Found:** - - Searched all HTML files for Google Analytics, Plausible, Matomo, tracking scripts - - No third-party analytics scripts present - - No analytics cookies being set - -2. **Privacy Policy Claims Analytics Exist:** - - Line 64: "Cookies: Session management, preferences (e.g., selected currency), **analytics**" - - Line 160: "**Analytics Cookies:** Privacy-respecting analytics (no cross-site tracking)" - -3. **Legitimate Data Storage Found:** - - `localStorage.tractatus_currency` - User's currency preference - - `localStorage.tractatus_search_history` - Docs search history - - `localStorage.auth_token` - Authentication token - - `localStorage.admin_token` - Admin panel authentication - - All legitimate, privacy-respecting uses - -4. **Admin Audit Analytics (Separate):** - - `/admin/audit-analytics.html` exists but is for **internal governance auditing** - - Tracks AI governance decisions (BoundaryEnforcer, etc.) - - NOT user behavior tracking - ---- - -## Options Analysis - -### Option A: Remove Analytics Claims from Privacy Policy - -**Approach:** Update privacy.html to remove all mentions of analytics cookies and tracking. - -**Pros:** -- Simple, immediate fix -- No new code to maintain -- Truly minimal data collection -- Zero privacy risk - -**Cons:** -- Lose visibility into basic usage patterns (which pages are valuable?) -- Can't measure impact of improvements -- Can't understand referrer sources (how did users find us?) -- Harder to demonstrate framework adoption/impact -- Privacy policy already published with analytics claim - -**Values Alignment:** βœ… Fully aligned with "Privacy-First Design" - ---- - -### Option B: Implement Privacy-Preserving Analytics (RECOMMENDED) - -**Approach:** Implement Plausible Analytics, a privacy-first analytics tool designed for GDPR/CCPA compliance. - -#### Why Plausible? - -**Privacy Guarantees:** -- βœ… No cookies used (100% cookie-free) -- βœ… No personal data collected (no IP logging, no fingerprinting) -- βœ… No cross-site tracking -- βœ… All data anonymized by default -- βœ… GDPR/CCPA/PECR compliant without cookie banners -- βœ… Open source (transparency) -- βœ… Lightweight (<1KB script vs. Google Analytics 45KB+) -- βœ… Does not slow down page load - -**Data Collected (All Anonymized):** -- Page views -- Referrer sources (where visitors came from) -- Browser/device type (general categories only) -- Country (derived from IP, not stored) -- Visit duration (aggregate, not individual tracking) - -**Data NOT Collected:** -- Individual IP addresses -- User identifiers -- Personal information -- Cross-site behavior -- Long-term tracking cookies - -**Values Alignment:** βœ… Aligns with "Privacy-First Design: minimal data collection" + provides value for improvement - ---- - -## Recommended Implementation: Plausible Analytics - -### Phase 1: Cloud-Hosted Plausible (Immediate) - -**Timeline:** 1-2 hours implementation - -**Approach:** -1. Sign up for Plausible Cloud ($9/month for up to 10k monthly pageviews) -2. Add single script tag to HTML pages: `` -3. Configure dashboard access (admin-only) -4. Update privacy.html to explicitly mention Plausible - -**Cost:** $9/month (~$108/year) - -**Pros:** -- Zero infrastructure maintenance -- Immediate implementation -- Professionally managed, high uptime -- EU/US data residency options -- Built-in dashboard - -**Cons:** -- Ongoing monthly cost -- Data hosted by third party (though anonymized) -- Less control over data sovereignty - ---- - -### Phase 2: Self-Hosted Plausible (Future, Phase 2+) - -**Timeline:** Phase 2 infrastructure work (Q2 2026) - -**Approach:** -1. Deploy Plausible CE (Community Edition) on VPS -2. PostgreSQL + ClickHouse database setup -3. Nginx reverse proxy configuration -4. Automated backups -5. Update script tag to point to self-hosted instance - -**Cost:** ~$20/month VPS increase (additional resources for PostgreSQL + ClickHouse) - -**Pros:** -- Complete data sovereignty -- One-time setup, no recurring licensing -- Full control over retention and access -- Aligns with "No Proprietary Lock-in" value - -**Cons:** -- Infrastructure complexity -- Requires ongoing maintenance -- Database management overhead -- Higher initial time investment - ---- - -## Privacy Policy Updates Required - -### Current (Line 160): -``` -Analytics Cookies: Privacy-respecting analytics (no cross-site tracking) -``` - -### Updated (Specific): -``` -Analytics: We use Plausible Analytics, a privacy-first, open-source analytics tool that: -- Does not use cookies -- Does not collect personal data -- Does not track you across websites -- Is fully GDPR/CCPA compliant -- Collects only anonymized, aggregate data (page views, referrers, country-level location) -- View our privacy-respecting analytics policy: https://plausible.io/privacy-focused-web-analytics -``` - -### Current (Line 64): -``` -Cookies: Session management, preferences (e.g., selected currency), analytics -``` - -### Updated: -``` -Cookies: Session management, user preferences (currency selection). Note: Our analytics tool (Plausible) does not use cookies. -``` - ---- - -## User Value Proposition - -**Why Minimal Analytics Benefits Users:** - -1. **Site Improvements:** Understanding which documentation pages are most helpful guides future content -2. **Bug Detection:** Unusual patterns (e.g., high bounce rate on a page) may indicate broken features -3. **Community Impact:** Demonstrating framework reach and adoption (anonymized, aggregate numbers) -4. **Resource Allocation:** Focus development effort on high-traffic, high-value features -5. **Transparency:** Public analytics dashboard option (Plausible supports this) - -**Privacy Trade-off:** Minimal anonymized data collection in exchange for better user experience and site quality. - ---- - -## Implementation Checklist - -### Phase 1: Cloud-Hosted Plausible - -- [ ] **HUMAN APPROVAL REQUIRED** - Values-sensitive decision (analytics implementation) -- [ ] Create Plausible Cloud account (admin credentials in password manager) -- [ ] Add domain: agenticgovernance.digital -- [ ] Add script tag to all HTML pages: - - [ ] index.html - - [ ] about.html, advocate.html, researcher.html, implementer.html, leader.html - - [ ] docs.html, blog.html, blog-post.html - - [ ] case-submission.html, media-inquiry.html - - [ ] privacy.html - - [ ] demos/*.html (4 files) - - [ ] admin/*.html (exempt from public analytics) -- [ ] Test script loading (check browser network tab) -- [ ] Verify data collection in Plausible dashboard (wait 24 hours for data) -- [ ] Update privacy.html with specific Plausible details -- [ ] Document admin access to Plausible dashboard -- [ ] (Optional) Make dashboard publicly viewable for transparency - -### Phase 2: Documentation - -- [ ] Create TRA-GOV-XXXX governance document for analytics policy -- [ ] Update CLAUDE.md with analytics approach -- [ ] Add section to integrated roadmap -- [ ] Document in PHASE-2-PREPARATION-ADVISORY.md - ---- - -## Boundary Enforcement Check - -**Question:** Is implementing privacy-preserving analytics a technical decision or a values decision? - -**Analysis:** -- **Values Dimension:** Privacy vs. Utility trade-off (even if minimal) -- **Strategic Impact:** Affects "Privacy-First Design" core value -- **User Impact:** Changes what data we collect (even if anonymized) -- **Transparency Requirement:** Must be disclosed to users - -**Classification:** βœ… **STRATEGIC** - Requires human approval per TRA-VAL-0001 - -**BoundaryEnforcer Assessment:** -``` -Action: Implement analytics (even privacy-preserving) -Domain: Values (Privacy vs. Utility) -Boundary Crossed: Yes - involves data collection philosophy -Human Approval Required: MANDATORY -Alternative: Option A (remove analytics claims entirely) -``` - ---- - -## Recommendation - -**Implement Plausible Analytics (Cloud-Hosted, Phase 1):** - -1. βœ… Aligns with "Privacy-First Design" (no tracking, no surveillance, minimal data) -2. βœ… Provides value for site improvement and community impact demonstration -3. βœ… Fixes privacy policy gap (claim matches implementation) -4. βœ… Minimal cost ($9/month) -5. βœ… Quick implementation (1-2 hours) -6. βœ… Clear path to self-hosting in Phase 2 (full sovereignty) -7. βœ… Open source, transparent, GDPR/CCPA compliant - -**Awaiting human approval to proceed.** - ---- - -## Alternatives Considered - -1. **Google Analytics** - ❌ Rejected: Violates privacy-first values, uses cookies, tracks users -2. **Matomo (cloud)** - ⚠️ Better than Google but more expensive, overkill for our needs -3. **Matomo (self-hosted)** - ⚠️ Good alternative but heavier than Plausible, more maintenance -4. **Simple Analytics** - ⚠️ Similar to Plausible but not open source -5. **Fathom Analytics** - ⚠️ Similar to Plausible but more expensive ($14/month vs $9/month) -6. **No analytics** - βœ… Valid choice but loses valuable insights - -**Winner:** Plausible (best balance of privacy, utility, cost, maintenance, transparency) - ---- - -## Questions for Human PM - -1. **Approve Option B (Plausible)?** Or prefer Option A (no analytics)? -2. **Dashboard visibility?** Keep private or make publicly viewable for transparency? -3. **Budget approval?** $9/month for Plausible Cloud? -4. **Timeline?** Implement immediately or defer to Phase 2? -5. **Self-hosting timeline?** Phase 2 infrastructure work or later? - ---- - -**Document Status:** DEFERRED - Scheduled for review November 2025 - -**Next Action:** Revisit in November 2025 for human PM review and decision - -**Deferral Rationale:** Privacy policy gap identified but not urgent. Site currently has no analytics (clean state). Decision deferred to allow time for consideration of values trade-offs. - ---- - -*This document was created by Claude (Session 2025-10-07-001) following the Tractatus governance framework. All values-sensitive decisions require human approval per TRA-VAL-0001.* diff --git a/docs/governance/TRA-VAL-0001-core-values-principles-v1-0.md b/docs/governance/TRA-VAL-0001-core-values-principles-v1-0.md deleted file mode 100644 index b422ea31..00000000 --- a/docs/governance/TRA-VAL-0001-core-values-principles-v1-0.md +++ /dev/null @@ -1,302 +0,0 @@ -# Tractatus AI Safety Framework - Core Values and Principles - -**Document Type:** Strategic Foundation -**Created:** 2025-10-06 -**Author:** John Stroh -**Version:** 1.0 -**Status:** Active -**Filename:** TRA-VAL-0001-core-values-principles-v1-0.md -**Document Code:** TRA-VAL-0001 -**Directory Path:** docs/governance/ -**Security Classification:** Public - -**Primary Quadrant:** STRATEGIC -**Related Quadrants:** OPS, TAC, SYS - -**Implements:** Tractatus Framework Specification v2.0 -**Implements Relationship:** Foundation -**Related Documents:** TRA-GOV-0001, TRA-GOV-0002, TRA-GOV-0003 -**Related Relationship:** Core -**Implementation Status:** Active - ---- - -## Purpose - -This document establishes the foundational values and principles that guide the Tractatus AI Safety Framework and all aspects of this website platform. These enduring elements represent our deepest commitments to safe AI development and provide the basis for strategic alignment across all features, content, and operations. - ---- - -## Core Values - -### Sovereignty & Self-determination -- **Human Agency Preservation**: AI systems must augment, never replace, human decision-making authority -- **User Control**: Individuals maintain complete control over their data and engagement with AI features -- **No Manipulation**: Zero dark patterns, no hidden AI influence, complete transparency in AI operations -- **Explicit Consent**: All AI features require clear user understanding and opt-in - -### Transparency & Honesty -- **Visible AI Reasoning**: All AI-generated suggestions include the reasoning process -- **Public Moderation Queue**: Human oversight decisions are documented and visible -- **Clear Boundaries**: Explicitly communicate what AI can and cannot do -- **Honest Limitations**: Acknowledge framework limitations and edge cases -- **No Proprietary Lock-in**: Open source, open standards, exportable data - -### Harmlessness & Protection -- **Privacy-First Design**: No tracking, no surveillance, minimal data collection -- **Security by Default**: Regular audits, penetration testing, zero-trust architecture -- **Fail-Safe Mechanisms**: AI errors default to human review, not automatic action -- **Boundary Enforcement**: Architectural guarantees prevent AI from making values decisions -- **User Safety**: Protection from AI-generated misinformation or harmful content - -### Human Judgment Primacy -- **Values Decisions**: Always require human approval, never delegated to AI -- **Strategic Oversight**: Human authority over mission, values, and governance -- **Escalation Protocols**: Clear pathways for AI to request human guidance -- **Override Capability**: Humans can always override AI suggestions -- **Accountability**: Human responsibility for all AI-assisted actions - -### Community & Accessibility -- **Universal Access**: Core framework documentation freely available to all -- **Three Audience Paths**: Tailored content for Researchers, Implementers, Advocates -- **Economic Accessibility**: Free tier with substantive capabilities -- **Knowledge Sharing**: Open collaboration, peer review, community contributions -- **WCAG Compliance**: Accessible to all abilities and assistive technologies - -### Biodiversity & Ecosystem Thinking -- **Multiple Valid Approaches**: No single solution, respect for alternative frameworks -- **Interoperability**: Integration with diverse AI safety approaches -- **Sustainability**: Long-term viability over short-term growth -- **Resilience**: Distributed systems, multiple mirrors, no single points of failure -- **Environmental Responsibility**: Green hosting, efficient code, minimal resource consumption - ---- - -## Guiding Principles - -### Architectural Safety Guarantees -- **Structural over Training**: Safety through architecture, not just fine-tuning -- **Explicit Boundaries**: Codified limits on AI action authority -- **Verifiable Compliance**: Automated checks against strategic values -- **Cross-Reference Validation**: AI actions validated against explicit instructions -- **Context Pressure Monitoring**: Detection of error-prone conditions - -### Dogfooding Implementation -- **Self-Application**: This website uses Tractatus to govern its own AI operations -- **Living Demonstration**: Platform proves framework effectiveness through use -- **Continuous Validation**: Real-world testing of governance mechanisms -- **Transparent Meta-Process**: Public documentation of how AI governs AI - -### Progressive Implementation -- **Phased Rollout**: 4-phase deployment over 18 months -- **Incremental Features**: Add capabilities as governance matures -- **No Shortcuts**: Quality over speed, world-class execution -- **Learn and Adapt**: Iterate based on real-world feedback - -### Education-Centered Approach -- **Demystify AI Safety**: Make complex concepts accessible -- **Build Literacy**: Empower users to understand AI governance -- **Interactive Demonstrations**: Learn by doing (classification, 27027 incident, boundary enforcement) -- **Case Study Learning**: Real-world failures and successes -- **Open Research**: Share findings, encourage replication - -### Jurisdictional Awareness & Data Sovereignty -- **Respect Indigenous Leadership**: Honor indigenous data sovereignty principles (CARE Principles) -- **Te Tiriti Foundation**: Acknowledge Te Tiriti o Waitangi as strategic baseline -- **Location-Aware Hosting**: Consider data residency and jurisdiction -- **Global Application**: Framework designed for worldwide implementation -- **Local Adaptation**: Support for cultural and legal contexts - -### AI Governance Framework -- **Quadrant-Based Classification**: Strategic/Operational/Tactical/System/Stochastic organization -- **Time-Persistence Metadata**: Instructions classified by longevity and importance -- **Human-AI Collaboration**: Clear delineation of authority and responsibility -- **Instruction Persistence**: Critical directives maintained across context windows -- **Metacognitive Verification**: AI self-assessment before proposing actions - -### Research & Validation Priority -- **Peer Review**: Academic rigor, scholarly publication -- **Reproducible Results**: Open code, documented methodologies -- **Falsifiability**: Framework designed to be tested and potentially disproven -- **Continuous Research**: Ongoing validation and refinement -- **Industry Collaboration**: Partnerships with AI organizations - -### Sustainable Operations -- **Koha Model**: Transparent, community-supported funding (Phase 3+) -- **No Exploitation**: Fair pricing, clear value exchange -- **Resource Efficiency**: Optimized code, cached content, minimal overhead -- **Long-Term Thinking**: Decades, not quarters -- **Community Ownership**: Contributors have stake in success - ---- - -## Te Tiriti o Waitangi Commitment - -**Strategic Baseline (Not Dominant Cultural Overlay):** - -The Tractatus framework acknowledges **Te Tiriti o Waitangi** and indigenous leadership in digital sovereignty as a strategic foundation for this work. We: - -- **Respect Indigenous Data Sovereignty**: Follow documented principles (CARE Principles, Te Mana Raraunga research) -- **Acknowledge Historical Leadership**: Indigenous peoples have led sovereignty struggles for centuries -- **Apply Published Standards**: Use peer-reviewed indigenous data governance frameworks -- **Defer Deep Engagement**: Will wait to approach Māori organizations until we have a stable and well developed platform in production. Our objective will be to request help in editing a Māori version that has their support and approval. - -**Implementation:** -- Footer acknowledgment (subtle, respectful) -- `/about/values` page (detailed explanation) -- Resource directory (links to Māori data sovereignty work) -- No tokenism, no performative gestures - ---- - -## Values Alignment in Practice - -### Content Curation (Blog, Resources) -- **AI Suggests**: Claude analyzes trends, proposes topics -- **Human Approves**: All values-sensitive content requires human review -- **Transparency**: AI reasoning visible in moderation queue -- **Attribution**: Clear "AI-curated, human-approved" labels - -### Media Inquiries -- **AI Triages**: Analyzes urgency, topic sensitivity -- **Human Responds**: All responses written or approved by humans -- **Escalation**: Values-sensitive topics immediately escalated to strategic review - -### Case Study Submissions -- **AI Reviews**: Assesses relevance, completeness -- **Human Validates**: Final publication decision always human -- **Quality Control**: Framework alignment checked against TRA-VAL-0001 - -### Interactive Demonstrations -- **Educational Purpose**: Teach framework concepts through interaction -- **No Live Data**: Demonstrations use example scenarios only -- **Transparency**: Show exactly how classification and validation work - ---- - -## Decision Framework - -When values conflict (e.g., transparency vs. privacy, speed vs. safety): - -1. **Explicit Recognition**: Acknowledge the tension publicly -2. **Context Analysis**: Consider specific situation and stakeholders -3. **Hierarchy Application**: - - Human Safety > System Performance - - Privacy > Convenience - - Transparency > Proprietary Advantage - - Long-term Sustainability > Short-term Growth -4. **Document Resolution**: Record decision rationale for future reference -5. **Community Input**: Seek feedback on significant value trade-offs - ---- - -## Review and Evolution - -### Annual Review Process -- **Scheduled:** 2026-10-06 (one year from creation) -- **Scope:** Comprehensive evaluation of values relevance and implementation -- **Authority:** Human PM (John Stroh) with community input -- **Outcome:** Updated version or reaffirmation of current values - -### Triggering Extraordinary Review -Immediate review required if: -- Framework fails to prevent significant AI harm -- Values found to be in conflict with actual operations -- Major regulatory or ethical landscape changes -- Community identifies fundamental misalignment - -### Evolution Constraints -- Core values (Sovereignty, Transparency, Harmlessness, Human Judgment) are **immutable** -- Guiding principles may evolve based on evidence and experience -- Changes require explicit human approval and public documentation - ---- - -## Metrics for Values Adherence - -### Sovereignty & Self-determination -- Zero instances of hidden AI influence -- 100% opt-in for AI features -- User data export capability maintained - -### Transparency & Honesty -- All AI reasoning documented in moderation queue -- Public disclosure of framework limitations -- Clear attribution of AI vs. human content - -### Harmlessness & Protection -- Zero security breaches -- Privacy audit pass rate: 100% -- Fail-safe activation rate (AI defers to human) - -### Human Judgment Primacy -- 100% of values decisions reviewed by humans -- Average escalation response time < 24 hours -- Zero unauthorized AI autonomous actions - -### Community & Accessibility -- WCAG AA compliance: 100% of pages -- Free tier usage: >80% of all users -- Community contributions accepted and integrated - ---- - -## Implementation Requirements - -All features, content, and operations must: - -1. **Pass Values Alignment Check**: Documented review against this framework -2. **Include Tractatus Governance**: Boundary enforcement, classification, validation -3. **Maintain Human Oversight**: Clear escalation paths to human authority -4. **Support Transparency**: Reasoning and decision processes visible -5. **Respect User Sovereignty**: No manipulation, complete control, clear consent - -**Failure to align with these values is grounds for feature rejection or removal.** - ---- - -## Appendix A: Values in Action Examples - -### Example 1: Blog Post Suggestion -**AI Action:** Suggests topic "Is AI Safety Overblown?" -**Classification:** STOCHASTIC (exploration) β†’ escalate to STRATEGIC (values-sensitive) -**Human Review:** Topic involves framework credibility, requires strategic approval -**Decision:** Approved with requirement for balanced, evidence-based treatment -**Outcome:** Blog post published with AI reasoning visible, cites peer-reviewed research - -### Example 2: Media Inquiry Response -**AI Action:** Triages inquiry from major tech publication as "high urgency" -**Classification:** OPERATIONAL (standard process) -**Human Review:** Response drafted by human, reviews AI summary for accuracy -**Decision:** Human-written response sent, AI triage saved time -**Outcome:** Effective media engagement, human authority maintained - -### Example 3: Feature Request -**AI Action:** Suggests adding "auto-approve" for low-risk blog posts -**Classification:** STRATEGIC (changes governance boundary) -**Human Review:** Would reduce human oversight, conflicts with core values -**Decision:** Rejected - all content requires human approval per TRA-VAL-0001 -**Outcome:** Framework integrity preserved, alternative efficiency improvements explored - ---- - -## Appendix B: Glossary - -**AI Governance:** Frameworks and mechanisms that control AI system behavior -**Boundary Enforcement:** Preventing AI from actions outside defined authority -**Dogfooding:** Using the framework to govern itself (meta-implementation) -**Human Judgment Primacy:** Core principle that humans retain decision authority -**Quadrant Classification:** Strategic/Operational/Tactical/System/Stochastic categorization -**Time-Persistence Metadata:** Instruction classification by longevity and importance -**Values-Sensitive:** Content or decisions that intersect with strategic values - ---- - -**Document Authority:** This document has final authority over all platform operations. In case of conflict between this document and any other guidance, TRA-VAL-0001 takes precedence. - -**Next Review:** 2026-10-06 -**Version History:** v1.0 (2025-10-06) - Initial creation - ---- - -*This document is maintained by John Stroh (john.stroh.nz@pm.me) and subject to annual review. Changes require explicit human approval and public documentation.*