Three scripts to support blog system improvements:
1. fix-blog-dates.js
- Fixes empty {} published_at values in database
- Sets proper ISODate values for 3 blogs
- Also updates moderation.approved_at for consistency
2. add-blog-categories.js
- Adds category field to all blog posts
- Maps content to standardized categories (Framework Updates,
Implementation, Case Studies)
- Enables category filtering functionality
3. add-vetting-notice-to-architectural-boundaries.js
- Adds comprehensive human vetting notice
- Documents AI-curated content review process
- Shows governance working end-to-end with inst_017 compliance
Applied to both tractatus_dev and tractatus_prod databases.
Ref: SESSION_HANDOFF_2025-10-23_WEBSITE_AUDIT.md
Problem: All MongoDB Date objects were being serialized as empty {} in API
responses, breaking blog date display across entire site.
Root Cause: removeSensitiveFields() function used spread operator on Date
objects ({...date}), which creates empty object because Dates have no
enumerable properties.
Fix: Added Date instance check before spreading to preserve Date objects
intact for proper JSON.stringify() serialization.
Impact:
- Fixes all blog dates showing 'Invalid Date'
- API now returns proper ISO date strings
- Deployed to production and verified working
Ref: SESSION_HANDOFF_2025-10-23_WEBSITE_AUDIT.md
- Converted all 9 accordion divs to semantic <button> elements
- Added ARIA attributes: aria-expanded, aria-controls, id for each button
- Accordion content: role="region" and aria-labelledby for screen readers
- Keyboard support: Enter and Space keys toggle accordions (WAI-ARIA pattern)
- Mobile optimization: 44px/48px touch targets, touch-action: manipulation
- iOS tap feedback: -webkit-tap-highlight-color
- Footer i18n: No footer object in leader.json (uses common.json correctly)
- Updated leader-page.js with keyboard handlers and ARIA state management
- Version 1.5.0
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Added diagrams from public tractatus-framework repo: architecture-main-flow.svg (6.6KB), trigger-decision-tree.svg (6.7KB)
- Diagram sizing: max-width 600px for readable display, responsive width 100%
- Fixed skip link: Added <main id="main-content"> wrapper for proper accessibility
- Quick navigation: 44px touch targets, flex-wrap for mobile, aria-label="Page sections"
- Download buttons: Descriptive ARIA labels, 44px minimum height
- Code blocks: Added role="region" and descriptive ARIA labels to all 6 service examples
- Mobile optimization: -webkit-overflow-scrolling, 11px code font on small screens, 16px body prevents iOS zoom
- API examples verified accurate against actual BoundaryEnforcer.service.js implementation
- CSP compliance: Moved diagram sizing to CSS class instead of inline styles
- Version 1.4.0
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Full WCAG accessibility: ARIA attributes (aria-expanded, aria-controls), keyboard navigation (Enter/Space)
- Reframed research context: Berlin/Weil as primary intellectual foundation (moral pluralism, categorical imperative)
- Bibliography with proper academic citations: Weil (The Need for Roots, Gravity and Grace), Berlin (Four Essays on Liberty)
- Fixed footer i18n: Implemented recursive deepMerge() to preserve nested translation objects
- Root cause: Shallow merge {...obj1, ...obj2} was overwriting entire footer object from common.json
- Consolidated all footer translations in common.json, removed from page-specific files
- Mobile optimization: 44px/48px touch targets, touch-action: manipulation, responsive design
- Progressive enhancement: <noscript> fallback for JavaScript-disabled users
- Version 1.3.0
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
IMPLEMENTER PAGE (public/implementer.html):
- Complete rewrite from 761 to 635 lines (developer-focused)
- Added both framework architecture diagrams (SVGs)
- Replaced fake @tractatus/framework npm package with real code examples
- Removed all marketing disclaimers and verbose filler
- Added technical specs for all 6 core services with real API examples
- Fixed GitHub repository links to match package.json
FOOTER FIXES (researcher.html, leader.html):
- Fixed script loading order (version-manager before i18n)
- Removed duplicate <!-- Footer --> comment in researcher.html
- Now matches index.html script structure for consistency
Result: Implementer page now shows actual framework documentation with real code examples and architecture diagrams
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
SECURITY CHANGES:
- Removed .github/workflows/sync-public-docs.yml (auto-synced to public repo)
- Removed 'public' git remote (tractatus-framework)
REASON:
Auto-syncing from private to public repository is inherently dangerous:
- Risks exposing internal files, credentials, or sensitive data
- No human review gate before public exposure
- Created the Stripe key exposure incident
GOING FORWARD:
- tractatus (private) = internal development repository
- tractatus-framework (public) = manually curated framework releases
- No automated sync between them
- Manual review required before any public release
This prevents automatic exposure of internal project files.
Removed files:
- SECURITY_INCIDENT_HUMAN_ACTIONS_REQUIRED.md (internal security doc)
- .claude/instruction-history.json (project-specific governance rules)
- scripts/add-security-rules-2025-10-21.js (dated, project-specific)
- scripts/apply-governance-audit-2025-10-21.js (dated, project-specific)
- docs/governance/GOVERNANCE_LEARNINGS_2025-10-21.md (internal learnings)
- docs/governance/GOVERNANCE_RULES_AUDIT_2025-10-21.md (internal audit)
These are internal to the tractatus project, not framework resources.
Public repo should contain only framework implementation code and docs.
Updated .gitignore to prevent future commits of similar files.
DECISION:
Maintain separate internal (tractatus) and public (tractatus-framework)
repositories with distinct purposes and content.
RATIONALE:
- Security: Internal research and strategy must not be public
- Clarity: Developers need implementation docs, not governance theory
- Professionalism: Public repo must appear world-class
- Prevent Misuse: "Bad actor bias" incident showed AI misrepresentation risk
PROCESS DOCUMENTED:
- 8-phase cleanup (615 → 96 files, 84% reduction)
- Professional documentation suite (CHANGELOG, SECURITY, README badges)
- GitHub Release v3.5.0 with downloadable packages
- Community features (Discussions enabled)
GOVERNANCE RULE CREATED:
- inst_063_CONSOLIDATED: Public GitHub Management
- Prohibits: Governance research, deliberation guides, theoretical frameworks
- Allows: Technical docs, API guides, code examples
- Requires: Weekly README review
BAD ACTOR BIAS INCIDENT:
AI suggested converting implementation docs to "governance guide for preventing
bad actors" - exact opposite of framework's pluralistic deliberation purpose.
inst_063_CONSOLIDATED now prevents this misrepresentation.
METRICS:
- Repository reduction: 84% fewer files
- README growth: +73% (215 → 372 lines)
- Documentation quality: Publication-ready
- Community ready: Discussions enabled, professional appearance
File: docs/architecture/ADR-001-public-repository-release-process.md (610 lines)
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Added community-ready documentation and policies:
CHANGELOG.md:
- Keep a Changelog format with semantic versioning
- Complete v3.5.0 release notes
- All 6 core services documented
- 4 support services listed
- Installation instructions
- Upgrade guide section
- Links to documentation and releases
SECURITY.md:
- Vulnerability reporting policy (security@agenticgovernance.digital)
- Supported versions table
- Security best practices for implementers
- Environment, network, deployment, database, API security
- Known security considerations
- Compliance information (OWASP Top 10)
- Security audit history
README.md improvements:
- Added release badge (v3.5.0)
- Added Node.js and MongoDB version badges
- Links to CHANGELOG.md and SECURITY.md at top
- Improved structure with clear sections
- Better code examples with context
- Added citation section (BibTeX format)
- Removed references to deleted files (systemd/, ADR-001)
- Corrected test counts (17 tests, not 625)
- Added Discussions link
- Professional status indicator
GitHub Discussions:
- Enabled via API for community engagement
Result: Repository now has professional documentation suite suitable
for public release and community adoption.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
BEFORE: 609-line research manifesto with:
- Research questions and theoretical framing
- "When the Framework Failed" case studies
- "Critical Open Problems" sections
- Extensive academic citations
- Audience: Researchers studying AI governance
AFTER: 215-line implementation guide with:
- Quick start (install, configure, run)
- Basic usage code examples
- API documentation links
- Deployment instructions
- Testing commands
- Clear website reference for background/research
- Audience: Developers implementing Tractatus
REMOVED:
- All research framing ("Research Question:", theoretical discussion)
- Case studies and failure documentation
- Academic positioning
- Fabrication incident disclosure
FOCUSED ON:
- Install/configure/deploy workflow
- Code examples developers can copy-paste
- Links to API docs and architecture docs
- Testing and contribution
Website (agenticgovernance.digital) now single source for background,
research, and general information. Public GitHub repository focused
exclusively on implementation.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
CRITICAL SECURITY:
- Removed 3,019 pptx-env Python virtualenv files from public tracking
- Added pptx-env/ to .gitignore
- Note: Stripe live key ALREADY removed in previous commit a6dc277
NEW CONTRIBUTING.md (world-class):
- Research-quality standards matching README
- Honest about alpha status (108 failing tests)
- Correct contact: research@agenticgovernance.digital
- No fabricated features or cultural positioning
- Rigorous testing/documentation standards
- Clear research ethics section
RESULT: Public GitHub now properly cleaned and documented
SECURITY INCIDENT:
- Stripe detected exposed live API key sk_live_***tMjIK
- Found hardcoded in create-live-prices.js and create-live-stripe-prices.js
- Files were pushed to public GitHub in previous commit
- Removing immediately and adding to .gitignore
ACTION REQUIRED:
User MUST rotate Stripe API keys immediately in Stripe Dashboard:
https://dashboard.stripe.com/apikeys
Files removed:
- scripts/create-live-prices.js
- scripts/create-live-stripe-prices.js
CRITICAL UPGRADE FROM POOR TO WORLD-CLASS:
USER FEEDBACK: "this is very poor work by Claude code. spend extra time and resource
on making the readme file as good as it can be and following all framework rules"
COMPREHENSIVE IMPROVEMENTS:
1. RESEARCH-QUALITY FRAMING:
- Every service introduced with research question
- Clear theoretical grounding (Berlin, Chang, Wittgenstein, March & Simon)
- Honest about what we know vs. don't know
- Explicit about limitations and open problems
2. VERIFIED ALL CLAIMS (inst_016 - no fabricated statistics):
- ✅ 52 active governance rules (verified from MongoDB)
- ✅ 625 passing tests (verified from npm test)
- ✅ 108 failing tests (transparent about failures)
- ✅ 349 commits since April 2025 (verified from git log)
- ✅ 28 test files (verified from file count)
- ❌ REMOVED "~500 Claude Code sessions" (unverified claim)
- ❌ REMOVED "100% coverage" (false claim)
3. NO ABSOLUTE ASSURANCE (inst_017):
- Changed: "structurally impossible" → "explores whether... structurally impossible"
- Changed: "ensures perfection" → "doesn't prevent failures"
- Changed: "guarantees safety" → "investigates structural constraints"
- Research language throughout: "explores", "investigates", "may"
4. NO UNVERIFIED READINESS (inst_018):
- Explicitly states: "NOT production-ready enterprise software"
- Explicitly states: "Research project with 108 known test failures"
- Removed all "enterprise-ready" / "production" language
- Clear positioning as "Alpha Research" phase
5. ARCHITECTURAL HONESTY:
- Full section on "When the Framework Failed" (fabrication incident)
- Transparent about false-positive/false-negative rates
- Honest about limited testing scope (single project, single domain)
- Clear about unresolved problems (rule proliferation, verification reliability)
6. COMPELLING NARRATIVE:
- Hook: "Can we build AI systems that structurally cannot make certain decisions?"
- Research findings with specific observational data
- Critical open problems with honest "we don't know"
- Philosophy section with deeper intellectual grounding
7. WORLD-CLASS STRUCTURE:
- Clear value propositions for researchers vs. implementers
- Comprehensive but readable (609 lines vs 425 lines)
- Professional tone without marketing hyperbole
- Proper academic attribution and acknowledgments
RESULT: GitHub README now genuinely world-class, intellectually rigorous, and
follows ALL framework rules for honesty and verification.
WHAT CHANGED:
- 418 insertions, 233 deletions
- Research question framing for all 6 services
- 3 critical open problems with honest status
- Full fabrication incident case study
- Verified claims, removed unverified claims
- Transparent about 108 failing tests
- Clear "NOT production-ready" positioning
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
CRITICAL SECURITY VIOLATION:
- Public website was linking to INTERNAL repository (tractatus)
- Should link to PUBLIC repository (tractatus-framework)
FIXES (5 instances across 3 pages):
- public/docs.html: 2 links (repository + readme)
- public/faq.html: 1 link (GitHub issues)
- public/implementer.html: 2 links (deployment guide + source code)
Changed:
github.com/AgenticGovernance/tractatus
→ github.com/AgenticGovernance/tractatus-framework
RESULT: Public website now correctly links to sanitized public repository
IMPACT: Prevents external users from accessing internal development files
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Updated i18n-simple.js and language-selector.js version to 1761023171
to force browser reload after translation fixes (inst_017 violations).
This ensures users see the corrected 'architectural constraints'
instead of cached 'architectural guarantees' text.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
ASSESSMENT: Framework effectiveness rated 4/10 this session
- Hooks work (reactive enforcement) ✅
- But don't guide decisions (proactive assistance) ❌
- Metrics collected but not actionable ❌
- Rules exist but aren't consulted during work ❌
KEY FINDING: Framework missed 15+ inst_017 violations for weeks
- Only caught when user manually requested audit
- No proactive scanning or detection
- Framework was REACTIVE, not PROACTIVE
TOP 3 IMPROVEMENTS PLANNED:
1. Proactive Content Scanning (5-7 hours)
- Auto-scan for inst_016/017/018 violations on session start
- Pre-commit hook to prevent violations
- Would have caught all 15 violations immediately
2. Context-Aware Rule Surfacing (8-9 hours)
- Surface relevant rules based on activity
- Editing markdown? Show inst_016/017/018
- Debugging? Show inst_050/024
- Makes 52 rules actionable when relevant
3. Active MetacognitiveVerifier (9-11 hours)
- Detect patterns (repeated failures, same file edited 5x)
- Suggest relevant solutions ("Try minimal reproduction")
- Would have guided integration test debugging
IMPLEMENTATION:
- Total effort: 32-40 hours (1 month part-time)
- Expected effectiveness: 4/10 → 8/10
- ROI: HIGH - Prevents violations, guides work, reduces debugging time
See: docs/framework-improvements/IMPLEMENTATION_PLAN_2025-10-21.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
PROBLEM: 10/26 integration test suites hanging (API tests)
- Tests import app but don't connect required databases
- Tractatus uses TWO separate DB connections (native + Mongoose)
- Tests only connected one, causing hangs when routes accessed User model
INVESTIGATION:
- Created minimal.test.js - diagnostic test (passes)
- Identified root cause: dual database architecture
- Updated api.auth.test.js with both connections (still investigating hang)
CREATED:
- tests/helpers/db-test-helper.js - Unified database setup helper
Exports setupDatabases() and cleanupDatabases()
Connects both native MongoDB driver AND Mongoose
Ready for use in all integration tests
PARTIAL FIX:
- tests/integration/api.auth.test.js - Updated to connect both DBs
- Still investigating why tests hang (likely response field mismatch)
NEXT SESSION:
1. Apply db-test-helper to all 7 API integration tests
2. Fix response field mismatches (accessToken vs token)
3. Verify all tests pass
IMPACT: Test helper provides pattern for fixing all integration tests
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
PROBLEM: Tests written for filesystem-based v1/v2, but service refactored to MongoDB v3
- 18/25 tests failing (expected filesystem, got MongoDB)
- Tests checking for .json files that no longer exist
- Response format mismatches (rulesStored vs inserted/modified)
SOLUTION: Complete test rewrite for MongoDB architecture
- Use GovernanceRule and AuditLog models directly
- Test data isolation with test_ prefix and cleanup hooks
- Updated assertions for MongoDB response formats
- Filter results to exclude non-test data from tractatus_test DB
- Removed filesystem-specific tests (directory creation, file I/O)
RESULT: 26/26 tests passing in 1.079s (from 7/25 in 250s timeout)
Tests now verify:
✓ MongoDB persistence and retrieval
✓ Rule filtering (quadrant, persistence)
✓ Cache management (TTL, clear, stats)
✓ Audit logging to MongoDB
✓ Data integrity across persist/load cycles
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
