From 19473fdbb6b9962363c68b9cc25ccd0c79cf7dde Mon Sep 17 00:00:00 2001 From: TheFlow Date: Tue, 7 Oct 2025 13:17:42 +1300 Subject: [PATCH] docs: Phase 2 kickoff materials & domain migration to agenticgovernance.digital MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit completes Phase 2 preparation with comprehensive kickoff materials and migrates all domain references from mysy.digital to agenticgovernance.digital. New Phase 2 Documents: - PHASE-2-PRESENTATION.md: 20-slide stakeholder presentation deck - PHASE-2-EMAIL-TEMPLATES.md: Invitation templates for 20-50 soft launch users - PHASE-2-KICKOFF-CHECKLIST.md: Comprehensive 12-week deployment checklist (200+ tasks) - PHASE-2-PREPARATION-ADVISORY.md: Advisory on achieving world-class UI/UX Domain Migration (mysy.digital → agenticgovernance.digital): - Updated CLAUDE.md project instructions - Updated README.md - Updated all Phase 2 planning documents (ROADMAP, COST-ESTIMATES, INFRASTRUCTURE) - Updated governance policies (TRA-OPS-0002, TRA-OPS-0003) - Updated framework documentation (introduction.md) - Updated implementation progress report Phase 2 Status: ✅ Budget approved: $550 USD for 3 months, $100-150/month ongoing ✅ Timeline confirmed: Starting NOW ✅ All 5 TRA-OPS-* governance policies approved ✅ Infrastructure decisions finalized (OVHCloud VPS Essential) ✅ Domain registered: agenticgovernance.digital Ready to Begin: - Week 1: Infrastructure deployment (VPS, DNS, SSL) - Week 5-8: AI features (Claude API, blog, media, case studies) - Week 9-12: Testing, governance audit, soft launch (20-50 users) Next Steps: 1. Provision OVHCloud VPS Essential (Singapore/Australia) 2. Configure DNS for agenticgovernance.digital 3. Generate secrets (JWT, MongoDB passwords) 4. Draft 3-5 initial blog posts (human-written) 5. Begin Week 1 infrastructure deployment 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 4 +- README.md | 2 +- docs/IMPLEMENTATION_PROGRESS_2025-10-07.md | 2 +- docs/PHASE-2-COST-ESTIMATES.md | 2 +- docs/PHASE-2-EMAIL-TEMPLATES.md | 547 +++++++++++++ docs/PHASE-2-INFRASTRUCTURE-PLAN.md | 34 +- docs/PHASE-2-KICKOFF-CHECKLIST.md | 769 ++++++++++++++++++ docs/PHASE-2-PREPARATION-ADVISORY.md | 604 ++++++++++++++ docs/PHASE-2-PRESENTATION.md | 533 ++++++++++++ docs/PHASE-2-ROADMAP.md | 10 +- docs/markdown/introduction.md | 2 +- ...OPS-0002-blog-editorial-guidelines-v1-0.md | 2 +- ...03-media-inquiry-response-protocol-v1-0.md | 16 +- 13 files changed, 2490 insertions(+), 37 deletions(-) create mode 100644 docs/PHASE-2-EMAIL-TEMPLATES.md create mode 100644 docs/PHASE-2-KICKOFF-CHECKLIST.md create mode 100644 docs/PHASE-2-PREPARATION-ADVISORY.md create mode 100644 docs/PHASE-2-PRESENTATION.md diff --git a/CLAUDE.md b/CLAUDE.md index 15113f4d..c71e6b1c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # Tractatus AI Safety Framework Website - Project Context **Project Name:** Tractatus Website Platform -**Domain:** mysy.digital +**Domain:** agenticgovernance.digital **Repository:** GitHub (primary) + Codeberg/Gitea (mirrors) **Status:** Development - Phase 1 Implementation **Created:** 2025-10-06 @@ -655,7 +655,7 @@ ADMIN_EMAIL=john.stroh.nz@pm.me **Not in Phase 1:** - Production deployment (OVHCloud) -- Domain configuration (mysy.digital) +- Domain configuration (agenticgovernance.digital) - ProtonBridge email integration - Koha donations (Phase 3) - Public launch diff --git a/README.md b/README.md index fdf38f67..48a90dc6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Tractatus AI Safety Framework Website **Status:** Development - Phase 1 Implementation -**Domain:** mysy.digital +**Domain:** agenticgovernance.digital **Project Start:** 2025-10-06 --- diff --git a/docs/IMPLEMENTATION_PROGRESS_2025-10-07.md b/docs/IMPLEMENTATION_PROGRESS_2025-10-07.md index f35d4ff9..57445240 100644 --- a/docs/IMPLEMENTATION_PROGRESS_2025-10-07.md +++ b/docs/IMPLEMENTATION_PROGRESS_2025-10-07.md @@ -434,7 +434,7 @@ This is the **first complete implementation of the Tractatus governance framewor **Phase 3+ (Production):** - OVHCloud hosting account -- Domain registration (mysy.digital) +- Domain registration (agenticgovernance.digital) - ProtonBridge for email - Stripe for Koha donations diff --git a/docs/PHASE-2-COST-ESTIMATES.md b/docs/PHASE-2-COST-ESTIMATES.md index cc79456e..1afc2117 100644 --- a/docs/PHASE-2-COST-ESTIMATES.md +++ b/docs/PHASE-2-COST-ESTIMATES.md @@ -43,7 +43,7 @@ | Item | Cost (USD) | Notes | |------|------------|-------| -| **Domain Registration** | $15-30/year | `mysy.digital` (if not already owned) | +| **Domain Registration** | $15-30/year | `agenticgovernance.digital` (if not already owned) | | **SSL Certificate** | $0 | Let's Encrypt (free) | | **Development Tools** | $0 | Open source (Git, Node.js, MongoDB) | | **Migration Services** | $0 | Self-managed deployment | diff --git a/docs/PHASE-2-EMAIL-TEMPLATES.md b/docs/PHASE-2-EMAIL-TEMPLATES.md new file mode 100644 index 00000000..f098a5d6 --- /dev/null +++ b/docs/PHASE-2-EMAIL-TEMPLATES.md @@ -0,0 +1,547 @@ +# Phase 2 Soft Launch Email Templates + +**Project**: Tractatus AI Safety Framework +**Phase**: 2 - Soft Launch Invitations +**Created**: 2025-10-07 +**Purpose**: Invite 20-50 users to early access +**Domain**: agenticgovernance.digital + +--- + +## Table of Contents + +1. [Invitation Strategy](#invitation-strategy) +2. [Template A: Researcher Invitation](#template-a-researcher-invitation) +3. [Template B: Implementer Invitation](#template-b-implementer-invitation) +4. [Template C: Advocate Invitation](#template-c-advocate-invitation) +5. [Template D: General Invitation](#template-d-general-invitation) +6. [Follow-Up Templates](#follow-up-templates) +7. [Feedback Request Template](#feedback-request-template) + +--- + +## Invitation Strategy + +### Target Cohort (20-50 users) + +| Audience | Count | Criteria | +|----------|-------|----------| +| **Researchers** | 8-12 | AI safety academics, PhD students, technical researchers | +| **Implementers** | 8-12 | AI engineers, architects, open-source developers | +| **Advocates** | 4-6 | AI policy professionals, digital rights organizations | +| **Total** | 20-30 | Quality over quantity for soft launch | + +### Invitation Timing + +**Week 10-11** (Phase 2 Month 3): +- All features deployed and tested +- Initial blog content published (3-5 posts) +- Case studies seeded (3-5 examples) +- System stable (monitoring confirms) + +### Personalization + +**Always include**: +- Recipient's name (first name friendly) +- Reason for invitation (specific to their work/interest) +- Personal note from John Stroh (when possible) + +--- + +## Template A: Researcher Invitation + +**Subject**: Early Access: Tractatus AI Safety Framework (Soft Launch) + +--- + +**Email Body**: + +Hi [First Name], + +I'm reaching out to invite you to the soft launch of the **Tractatus AI Safety Framework** platform at **agenticgovernance.digital**. + +**Why this might interest you:** + +You've published extensively on [specific topic: AI alignment, constitutional AI, etc.], and the Tractatus framework offers a complementary approach through **architectural constraints** rather than behavioral alignment. I think you'd find the framework's core principle particularly relevant: + +> *"What cannot be systematized must not be automated."* + +**What is Tractatus?** + +Tractatus is the world's first production implementation of AI safety through architectural boundaries. Instead of hoping AI systems "behave correctly," we implement structural guarantees that certain decision types (values, ethics, agency) architecturally require human judgment. + +Think of it as runtime enforcement of the principle: *The limits of automation are the limits of systemization.* + +**What's on the platform:** + +- **Technical documentation**: Full framework specification, formal proofs, architectural diagrams +- **Interactive demonstrations**: See how boundary enforcement prevents the documented "27027 incident" (instruction override failure) +- **Case studies**: Real-world AI failures analyzed through the Tractatus lens +- **Research papers**: Appendices on scholarly context, related work, theoretical foundations + +**Why early access?** + +We're inviting 20-30 researchers, implementers, and advocates to provide feedback before public launch. Your insights on [specific aspect: theoretical foundations, empirical validation, etc.] would be invaluable. + +**Access details:** + +- Platform: https://agenticgovernance.digital +- Duration: 4-6 weeks (feedback period) +- What we need: 15-minute feedback survey + optional follow-up discussion +- Anonymity: Your feedback can be anonymous if preferred + +**Getting started:** + +1. Visit https://agenticgovernance.digital/researcher +2. Explore the framework documentation +3. Try the interactive demos (especially the 27027 incident visualizer) +4. Share your thoughts via the feedback form + +**Questions?** + +Reply to this email or reach me at john.stroh.nz@pm.me. I'm happy to schedule a brief discussion if you'd like to dive deeper. + +**Citation & Attribution:** + +If you reference the framework in your work, please cite: +> Stroh, J. (2025). Tractatus-Based LLM Architecture for AI Safety. agenticgovernance.digital + +Thank you for considering this invitation. I'm genuinely curious to hear your perspective—especially any critical feedback or alternative approaches. + +Best regards, +**John Stroh** +Founder, Tractatus Framework +agenticgovernance.digital + +P.S. The platform itself is governed by the Tractatus framework (dogfooding). All AI-assisted content (blog posts, media responses) requires human approval. No values decisions are automated. + +--- + +**Attachments** (optional): +- Tractatus_Framework_Executive_Summary.pdf +- 27027_Incident_Case_Study.pdf + +--- + +## Template B: Implementer Invitation + +**Subject**: Invitation: Test-Drive the Tractatus AI Safety Framework + +--- + +**Email Body**: + +Hi [First Name], + +I saw your work on [specific project: open-source LLM tool, AI safety library, etc.] and thought you'd appreciate a hands-on look at the **Tractatus AI Safety Framework**. + +**What is it?** + +Tractatus is an architectural AI safety framework that enforces runtime constraints on LLM operations. It's not about prompting or fine-tuning—it's about **structural boundaries** that prevent certain classes of failures regardless of model capabilities. + +**The core idea:** + +Instead of hoping AI systems stay aligned, we implement architectural checks that certain decision types (values, ethics, ambiguous instructions) **cannot be executed** without human approval. + +**Example: The "27027 Incident"** + +User explicitly instructs: *"Use MongoDB on port 27017"* +AI generates code: `const PORT = 27027; // Pattern-matched, wrong!` + +**Tractatus solution:** +```javascript +const validator = new CrossReferenceValidator(); +const action = { port: 27027 }; +const instruction = { port: 27017, persistence: 'HIGH' }; + +const result = validator.validate(action, instruction); +// result.status: 'REJECTED' +// result.reason: 'Conflicts with explicit instruction #42' +``` + +**Why early access?** + +We're soft-launching to 20-30 users (researchers, developers, advocates) and would love your feedback on: +- API design & developer experience +- Integration patterns (how would you use this in production?) +- Performance considerations +- Documentation clarity + +**What's available:** + +- **Implementation guide**: https://agenticgovernance.digital/implementer +- **API reference**: Full REST API documentation with examples +- **Code examples**: Production-ready snippets for 5 framework components +- **Interactive demos**: See boundary enforcement in action + +**Getting started:** + +1. Visit https://agenticgovernance.digital/implementer +2. Review the implementation guide (step-by-step integration) +3. Try the API (read-only access, no auth required for demos) +4. Share feedback: What would you change? What's missing? + +**Feedback incentive:** + +We're considering open-sourcing the framework (Phase 3). Your input will directly shape the public API design. Plus, early contributors will be acknowledged in the project README. + +**Technical specs:** + +- Node.js 18+, Express 4.x, MongoDB 7.x +- Designed for middleware integration (plug into existing apps) +- Zero external dependencies (except optional Claude API) +- MIT License (planned) + +**Questions?** + +Reply to this email or ping me at john.stroh.nz@pm.me. I'm happy to jump on a call to discuss technical details. + +Thanks for considering! Looking forward to your thoughts. + +Best, +**John Stroh** +Founder, Tractatus Framework +agenticgovernance.digital + +P.S. The framework is TypeScript-friendly (type definitions coming in v1.1). + +--- + +**Attachments** (optional): +- Tractatus_API_Quick_Start.pdf +- Integration_Patterns_Guide.pdf + +--- + +## Template C: Advocate Invitation + +**Subject**: Join the Soft Launch: AI Safety Through Sovereignty + +--- + +**Email Body**: + +Hi [First Name], + +I've been following your work on [specific advocacy: digital rights, AI policy, ethical tech] and wanted to invite you to explore the **Tractatus AI Safety Framework**—a new approach to AI safety grounded in **human sovereignty**. + +**The core principle:** + +> *"What cannot be systematized must not be automated."* + +This means: AI systems should not make decisions involving values, ethics, or human agency. Those decisions are inherently unsystemizable and must remain with humans. + +**Why this matters for advocacy:** + +Current AI safety approaches (alignment, RLHF, constitutional AI) try to encode values into AI systems. But values are contested, contextual, and evolving. **Tractatus offers an alternative**: architectural constraints that ensure AI defers to humans for values-laden decisions. + +**Think of it as:** +- **Digital sovereignty** applied to AI governance +- **Bounded automation**: AI does what it's good at; humans decide what matters +- **Structural safety**: Not "teach AI to be good" but "prevent AI from deciding what 'good' means" + +**Real-world example: Media inquiry handling** + +Without Tractatus: +- AI classifies inquiry, drafts response, **sends email automatically** +- Risk: AI makes judgment call on what deserves a response (values decision) + +With Tractatus: +- AI classifies inquiry, drafts response, **human approves before sending** +- Boundary enforced: External communication requires human judgment + +**What's on the platform:** + +- **Plain-language explanations**: No PhD required (but technical details available) +- **Case studies**: Real-world AI failures analyzed for policy lessons +- **Interactive demos**: See how boundary enforcement prevents harmful automation +- **Advocacy toolkit**: Policy implications, regulatory alignment, talking points + +**Why early access?** + +We're inviting 20-30 people (researchers, developers, advocates) to shape the public launch. Your perspective on [specific area: policy implications, user agency, regulatory fit] would be invaluable. + +**Getting started:** + +1. Visit https://agenticgovernance.digital/advocate +2. Read "AI Safety as Human Sovereignty" (5-minute intro) +3. Explore case studies (real incidents where Tractatus would help) +4. Share feedback: How can we better communicate this to policymakers? + +**Feedback we need:** + +- Is the message clear for non-technical audiences? +- What policy implications are we missing? +- How would you explain this to [regulators, journalists, public]? +- What concerns or objections should we address? + +**Your voice matters:** + +This isn't just a technical project—it's a vision for AI governance that respects human agency. We need advocates like you to help shape the narrative and ensure it serves the public interest. + +**Questions?** + +Reply to this email or reach me at john.stroh.nz@pm.me. I'd love to discuss how this framework aligns (or doesn't!) with your advocacy goals. + +Thank you for considering this invitation. Looking forward to your insights. + +Best regards, +**John Stroh** +Founder, Tractatus Framework +agenticgovernance.digital + +P.S. The framework acknowledges Te Tiriti o Waitangi and indigenous data sovereignty principles (CARE). Digital sovereignty is universal, but implementation must respect local context. + +--- + +**Attachments** (optional): +- Tractatus_Policy_Brief.pdf +- AI_Safety_as_Sovereignty_Essay.pdf + +--- + +## Template D: General Invitation + +**Subject**: You're Invited: Tractatus AI Safety Framework (Soft Launch) + +--- + +**Email Body**: + +Hi [First Name], + +I'm excited to invite you to the soft launch of **agenticgovernance.digital**, a new platform demonstrating AI safety through architectural constraints. + +**Quick intro:** + +The **Tractatus Framework** is the world's first production implementation of runtime boundary enforcement for AI systems. Core principle: + +> *"What cannot be systematized must not be automated."* + +In practice: AI systems must defer to humans for decisions involving values, ethics, or ambiguity. This is enforced architecturally (not behaviorally). + +**What you'll find:** + +- **Documentation**: Full framework specification +- **Demos**: Interactive visualizations of boundary enforcement +- **Blog**: AI safety insights, case studies, technical deep dives +- **Community**: Case study submissions, discussions (coming soon) + +**Why early access?** + +We're inviting 20-30 people for feedback before public launch. Your perspective would help us: +- Improve clarity (is the framework understandable?) +- Identify gaps (what's missing?) +- Refine messaging (how do we explain this to different audiences?) + +**Getting started:** + +Visit: https://agenticgovernance.digital + +Choose your path: +- **Researcher**: Academic & technical depth +- **Implementer**: Code examples & API docs +- **Advocate**: Policy implications & plain language + +**Feedback:** + +After exploring, please share your thoughts via the feedback form (15 minutes). Optional: I'm happy to schedule a follow-up discussion. + +**Questions?** + +Reply to this email or contact me at john.stroh.nz@pm.me. + +Thanks for your time and interest. Looking forward to hearing from you! + +Best, +**John Stroh** +Founder, Tractatus Framework +agenticgovernance.digital + +--- + +## Follow-Up Templates + +### Template E: Reminder (1 Week After Invitation) + +**Subject**: Reminder: Tractatus Soft Launch Feedback + +--- + +Hi [First Name], + +Quick follow-up on my invitation to explore the Tractatus AI Safety Framework at **agenticgovernance.digital**. + +No pressure—just wanted to make sure the email didn't get lost in your inbox! + +**Quick access:** +- Platform: https://agenticgovernance.digital/[researcher|implementer|advocate] +- Feedback form: 15 minutes +- Deadline: [Date - 3 weeks from invitation] + +If you're not interested or too busy, no worries—just let me know and I'll stop bothering you. 😊 + +Thanks, +**John Stroh** + +--- + +### Template F: Thank You (After Feedback Received) + +**Subject**: Thank you for your Tractatus feedback! + +--- + +Hi [First Name], + +Thank you for taking the time to explore agenticgovernance.digital and share your feedback! + +**Your insights:** + +[Personalized response to their specific feedback points] + +**What's next:** + +We're incorporating feedback from all early users and will share an updated roadmap in [timeframe]. If you're interested, I'll keep you posted on: +- Public launch (Phase 3) +- Open-source release +- Community features (forums, discussions) + +**Stay in touch?** + +Would you like to stay updated on the project? I can add you to our low-volume newsletter (1 email/month, unsubscribe anytime). + +Thanks again for your thoughtful input. It's genuinely helpful. + +Best, +**John Stroh** + +--- + +### Template G: Non-Responder Follow-Up (2 Weeks After Reminder) + +**Subject**: Last call: Tractatus feedback (no worries if too busy!) + +--- + +Hi [First Name], + +Final follow-up on the Tractatus soft launch invitation. + +I know inboxes are overwhelming, so no hard feelings if you're not interested or don't have time! + +If you *are* interested but haven't had a chance yet, the feedback window is open for [X more days]. + +Otherwise, I'll assume it's not a priority and won't bother you further. 😊 + +Thanks for considering it! + +Best, +**John Stroh** + +--- + +## Feedback Request Template + +### Template H: Structured Feedback Survey (Google Form or TypeForm) + +**Survey Link**: [To be created] + +**Questions** (15 minutes estimated): + +**Section 1: Background** +1. Which audience path did you explore? (Researcher / Implementer / Advocate / All) +2. How would you describe your background? (Academia / Industry / Policy / Other) +3. How did you learn about Tractatus? (Email invitation / Other) + +**Section 2: Clarity** +4. How clear is the framework's core principle? (1-5 scale) +5. What was confusing or unclear? (Open text) +6. What was most interesting or valuable? (Open text) + +**Section 3: Content** +7. Which sections did you explore? (Check all: Docs, Demos, Blog, API Reference) +8. What's missing that you expected to find? (Open text) +9. How useful are the interactive demos? (1-5 scale) + +**Section 4: Technical (If Applicable)** +10. Would you consider integrating Tractatus into your work? (Yes / Maybe / No / N/A) +11. What technical concerns or barriers do you see? (Open text) + +**Section 5: Messaging** +12. How would you explain Tractatus to a colleague? (Open text) +13. What's the strongest argument for this approach? (Open text) +14. What's the strongest argument against this approach? (Open text) + +**Section 6: Overall** +15. Overall satisfaction with the platform? (1-5 scale) +16. Would you recommend Tractatus to others? (Yes / Maybe / No) +17. Any other feedback or suggestions? (Open text) + +**Section 7: Follow-Up** +18. Can we follow up with you for clarification? (Yes / No) +19. Would you like updates on the public launch? (Yes / No) +20. Email for follow-up: (Optional) + +--- + +## Invitation Checklist + +### Before Sending Invitations + +- [ ] Platform stable (agenticgovernance.digital live and tested) +- [ ] Blog content published (3-5 initial posts) +- [ ] Case studies seeded (3-5 examples) +- [ ] Feedback survey created (Google Form or TypeForm) +- [ ] Recipient list finalized (20-30 users across 3 audiences) + +### Sending Process + +- [ ] Personalize each email (name, reason for invitation, specific detail) +- [ ] Send from john.stroh.nz@pm.me (personal, not automated) +- [ ] BCC all recipients (privacy) +- [ ] Track responses (spreadsheet: Invited, Responded, Feedback Received) +- [ ] Schedule reminders (1 week, 2 weeks) + +### After Launch + +- [ ] Monitor feedback form responses daily +- [ ] Respond to all feedback within 48 hours (thank you notes) +- [ ] Compile feedback themes weekly +- [ ] Iterate on platform based on insights +- [ ] Share summary report with all participants (transparency) + +--- + +## Metrics to Track + +### Response Rates + +| Metric | Target | Actual | +|--------|--------|--------| +| **Invitation sent** | 30 | - | +| **Email opened** | 70% (21) | - | +| **Platform visited** | 50% (15) | - | +| **Feedback submitted** | 30% (9) | - | + +### Satisfaction + +| Metric | Target | Actual | +|--------|--------|--------| +| **Overall satisfaction** | 4+/5 | - | +| **Would recommend** | 70% Yes | - | +| **Critical feedback** | <30% | - | + +--- + +## Revision History + +| Date | Version | Changes | +|------|---------|---------| +| 2025-10-07 | 1.0 | Initial email templates for Phase 2 soft launch | + +--- + +**Document Owner**: John Stroh +**Last Updated**: 2025-10-07 +**Next Review**: After soft launch (Week 12) diff --git a/docs/PHASE-2-INFRASTRUCTURE-PLAN.md b/docs/PHASE-2-INFRASTRUCTURE-PLAN.md index 4680addc..27caea05 100644 --- a/docs/PHASE-2-INFRASTRUCTURE-PLAN.md +++ b/docs/PHASE-2-INFRASTRUCTURE-PLAN.md @@ -41,7 +41,7 @@ │ ┌────────▼────────┐ │ OVHCloud VPS │ (Ubuntu 22.04 LTS) - │ mysy.digital │ + │ agenticgovernance.digital │ └────────┬────────┘ │ ┌────────────┴────────────┐ @@ -414,9 +414,9 @@ CLAUDE_MAX_TOKENS=200000 # Email (ProtonBridge) SMTP_HOST=127.0.0.1 SMTP_PORT=1025 -SMTP_USER=contact@mysy.digital +SMTP_USER=contact@agenticgovernance.digital SMTP_PASSWORD= -SMTP_FROM=contact@mysy.digital +SMTP_FROM=contact@agenticgovernance.digital # Admin ADMIN_EMAIL=john.stroh.nz@pm.me @@ -477,7 +477,7 @@ sudo nano /etc/systemd/system/tractatus.service ```ini [Unit] Description=Tractatus AI Safety Framework -Documentation=https://mysy.digital/docs +Documentation=https://agenticgovernance.digital/docs After=network.target mongod.service [Service] @@ -540,7 +540,7 @@ upstream tractatus_app { server { listen 80; listen [::]:80; - server_name mysy.digital www.mysy.digital; + server_name agenticgovernance.digital www.agenticgovernance.digital; # Let's Encrypt verification location /.well-known/acme-challenge/ { @@ -557,12 +557,12 @@ server { server { listen 443 ssl http2; listen [::]:443 ssl http2; - server_name mysy.digital www.mysy.digital; + server_name agenticgovernance.digital www.agenticgovernance.digital; # SSL certificates (Let's Encrypt) - ssl_certificate /etc/letsencrypt/live/mysy.digital/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/mysy.digital/privkey.pem; - ssl_trusted_certificate /etc/letsencrypt/live/mysy.digital/chain.pem; + ssl_certificate /etc/letsencrypt/live/agenticgovernance.digital/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/agenticgovernance.digital/privkey.pem; + ssl_trusted_certificate /etc/letsencrypt/live/agenticgovernance.digital/chain.pem; # SSL configuration (Mozilla Intermediate) ssl_protocols TLSv1.2 TLSv1.3; @@ -672,7 +672,7 @@ sudo systemctl reload nginx ```bash # Obtain SSL certificate -sudo certbot --nginx -d mysy.digital -d www.mysy.digital +sudo certbot --nginx -d agenticgovernance.digital -d www.agenticgovernance.digital # Follow prompts: # - Enter email: john.stroh.nz@pm.me @@ -830,7 +830,7 @@ sudo nano /usr/local/bin/tractatus-healthcheck.sh #!/bin/bash # Healthcheck endpoint -URL="https://mysy.digital/health" +URL="https://agenticgovernance.digital/health" # Check if site is up HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" $URL) @@ -942,7 +942,7 @@ mongorestore --db tractatus_prod /tmp/YYYYMMDD/tractatus_prod 5. **Verify**: ```bash -curl https://mysy.digital/health +curl https://agenticgovernance.digital/health ``` **RTO** (Recovery Time Objective): <4 hours @@ -1020,7 +1020,7 @@ ls -l /var/www/tractatus/.env.production ### Pre-Deployment - [ ] OVHCloud VPS provisioned (Essential tier) -- [ ] Domain registered (mysy.digital) +- [ ] Domain registered (agenticgovernance.digital) - [ ] Cloudflare account created (optional) - [ ] DNS configured (A/AAAA records pointing to server) - [ ] SSH key generated and added to server @@ -1089,10 +1089,10 @@ ls -l /var/www/tractatus/.env.production ### Testing -- [ ] Homepage loads: https://mysy.digital/ -- [ ] API health check: https://mysy.digital/health -- [ ] Document viewer: https://mysy.digital/docs-viewer.html -- [ ] Admin login: https://mysy.digital/admin/login.html +- [ ] Homepage loads: https://agenticgovernance.digital/ +- [ ] API health check: https://agenticgovernance.digital/health +- [ ] Document viewer: https://agenticgovernance.digital/docs-viewer.html +- [ ] Admin login: https://agenticgovernance.digital/admin/login.html - [ ] Static assets loading (CSS, JS) - [ ] CSP compliance (no console errors) - [ ] Mobile responsiveness (test on phone) diff --git a/docs/PHASE-2-KICKOFF-CHECKLIST.md b/docs/PHASE-2-KICKOFF-CHECKLIST.md new file mode 100644 index 00000000..cd7a5791 --- /dev/null +++ b/docs/PHASE-2-KICKOFF-CHECKLIST.md @@ -0,0 +1,769 @@ +# Phase 2 Kickoff Checklist + +**Project**: Tractatus AI Safety Framework +**Phase**: 2 - Production Deployment & AI Features +**Duration**: 2-3 months (12 weeks) +**Status**: APPROVED - Ready to Execute +**Domain**: agenticgovernance.digital + +--- + +## Overview + +This checklist provides a step-by-step guide for executing Phase 2 deployment. Complete each section sequentially to ensure smooth deployment and avoid missing critical steps. + +**Color Coding**: +- ✅ Complete +- 🔄 In Progress +- ⏳ Pending (blocked or scheduled for later) +- ❌ Not Started + +--- + +## Pre-Kickoff (Week 0) + +### Administrative Setup + +- [ ] **Sign TRA-OPS-* Governance Documents** + - TRA-OPS-0001: AI Content Generation Policy + - TRA-OPS-0002: Blog Editorial Guidelines + - TRA-OPS-0003: Media Inquiry Response Protocol + - TRA-OPS-0004: Case Study Moderation Standards + - TRA-OPS-0005: Human Oversight Requirements + - **Action**: Add digital signature or email confirmation to John Stroh + +- [ ] **Budget Approval Documentation** + - Phase 2 total: $550 USD (~$900 NZD) + - Monthly ongoing: $100-150 USD + - **Action**: Document approval (email, spreadsheet, or formal doc) + +- [ ] **Payment Methods Setup** + - OVHCloud account created + - Payment method added (credit card or PayPal) + - Anthropic account created (for Claude API) + - Payment method added to Anthropic + - **Action**: Verify both accounts have valid payment methods + +--- + +### Account Creation + +- [ ] **OVHCloud Account** + - Account created: ___________ + - Email verified: ___________ + - 2FA enabled: ___________ + - **Login**: Save credentials securely (password manager) + +- [ ] **Anthropic Claude API Account** + - Account created: ___________ + - Email verified: ___________ + - Production API key generated: ___________ + - **Security**: Store API key in password manager (NEVER commit to Git) + +- [ ] **Domain Configuration** + - Domain: agenticgovernance.digital ✅ (already registered) + - Registrar: OVHCloud ✅ + - Auto-renewal enabled: ___________ + - Registrar lock enabled: ___________ + +--- + +### Security Preparation + +- [ ] **SSH Key Generation** + - Generate ED25519 key: `ssh-keygen -t ed25519 -C "tractatus-deploy"` + - Key location: `~/.ssh/tractatus_ed25519` + - Public key copied: `~/.ssh/tractatus_ed25519.pub` + - **Action**: Save private key securely, NEVER share + +- [ ] **Secret Generation** + - JWT_SECRET (64 chars): `node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"` + - MongoDB password (32 chars): `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"` + - **Action**: Store in password manager, ready for .env.production + +- [ ] **Email Configuration** + - ProtonMail account: john.stroh.nz@pm.me ✅ (existing) + - ProtonBridge installed: ___________ + - SMTP credentials ready: ___________ + +--- + +## Week 1: Infrastructure Setup + +### Day 1-2: Server Provisioning + +- [ ] **Provision OVHCloud VPS** + - Login to OVHCloud control panel + - Select: VPS Essential (2 vCore, 4GB RAM, 80GB SSD) + - Region: Singapore or Australia (preferred) + - OS: Ubuntu 22.04 LTS + - Generate root password (save securely) + - Provision server (5-10 minutes) + - **Server IP**: ___.___.___.___ + +- [ ] **Initial Server Access** + - SSH to server as root: `ssh root@` + - Update system: `apt update && apt upgrade -y` + - Verify Ubuntu version: `lsb_release -a` (should be 22.04) + +- [ ] **Create Non-Root User** + - Create user: `adduser tractatus` + - Add to sudo: `usermod -aG sudo tractatus` + - Set up SSH dir: `mkdir -p /home/tractatus/.ssh && chmod 700 /home/tractatus/.ssh` + - Copy public key: `ssh-copy-id tractatus@` + - Test login: `ssh tractatus@` + - **Verify**: Can login as tractatus with SSH key + +### Day 3: Security Hardening + +- [ ] **SSH Hardening** + - Edit config: `sudo nano /etc/ssh/sshd_config` + - Set: `PermitRootLogin no` + - Set: `PasswordAuthentication no` + - Set: `PubkeyAuthentication yes` + - Set: `AllowUsers tractatus` + - Restart SSH: `sudo systemctl restart sshd` + - **Test**: Try SSH as root (should FAIL) + +- [ ] **Firewall Setup (UFW)** + - Allow SSH from your IP: `sudo ufw allow from to any port 22` + - Allow HTTP: `sudo ufw allow 80/tcp` + - Allow HTTPS: `sudo ufw allow 443/tcp` + - Enable: `sudo ufw enable` + - Verify: `sudo ufw status verbose` + - **Check**: Port 22 restricted, 80/443 open + +- [ ] **Fail2ban Installation** + - Install: `sudo apt install -y fail2ban` + - Copy config: `sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local` + - Enable SSH jail: Edit `/etc/fail2ban/jail.local`, set `[sshd] enabled = true` + - Restart: `sudo systemctl restart fail2ban` + - Verify: `sudo fail2ban-client status` + +- [ ] **Automatic Security Updates** + - Install: `sudo apt install -y unattended-upgrades` + - Configure: `sudo dpkg-reconfigure -plow unattended-upgrades` (select Yes) + - Verify: `cat /etc/apt/apt.conf.d/20auto-upgrades` + +### Day 4-5: Application Stack Installation + +- [ ] **Install Node.js 18 LTS** + - Add repository: `curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -` + - Install: `sudo apt install -y nodejs` + - Verify: `node --version` (should be v18.x.x) + - Verify: `npm --version` (should be 9.x.x or higher) + +- [ ] **Install MongoDB 7.x** + - Add GPG key: `curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/mongodb-server-7.0.gpg` + - Add repository: `echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list` + - Update: `sudo apt update` + - Install: `sudo apt install -y mongodb-org` + - Start: `sudo systemctl start mongod` + - Enable: `sudo systemctl enable mongod` + - Verify: `mongosh --eval 'db.version()'` (should be 7.0.x) + +- [ ] **Install Nginx** + - Install: `sudo apt install -y nginx` + - Start: `sudo systemctl start nginx` + - Enable: `sudo systemctl enable nginx` + - Verify: `curl http://` (should see "Welcome to nginx") + +- [ ] **Install Additional Tools** + - Install: `sudo apt install -y git curl wget vim htop certbot python3-certbot-nginx` + - Verify Git: `git --version` + - Verify Certbot: `certbot --version` + +--- + +## Week 2: Application Deployment + +### Day 6-7: DNS Configuration + +- [ ] **Configure OVHCloud DNS** + - Login to OVHCloud control panel + - Navigate to: Domains → agenticgovernance.digital → DNS Zone + - Add A record: + - Type: A + - Subdomain: @ (root) + - Target: + - TTL: 3600 + - Add A record for www: + - Type: A + - Subdomain: www + - Target: + - TTL: 3600 + - Add AAAA record (IPv6, if available): + - Type: AAAA + - Subdomain: @ + - Target: + - **Wait**: DNS propagation (24-48 hours max, usually <2 hours) + +- [ ] **Verify DNS Propagation** + - Check A record: `dig agenticgovernance.digital +short` + - Check www: `dig www.agenticgovernance.digital +short` + - Online check: https://dnschecker.org + - **Confirm**: Both @ and www resolve to server IP + +### Day 8-9: Application Code Deployment + +- [ ] **Create Application Directory** + - Create: `sudo mkdir -p /var/www/tractatus` + - Ownership: `sudo chown tractatus:tractatus /var/www/tractatus` + - Permissions: `sudo chmod 755 /var/www/tractatus` + +- [ ] **Clone Repository** + - Navigate: `cd /var/www/tractatus` + - Clone: `git clone https://github.com/your-org/tractatus.git .` + - **If private repo**: Set up deploy key first + - Verify: `ls -la` (should see package.json, src/, public/, etc.) + +- [ ] **Install Dependencies** + - Install production: `npm install --production` + - **Wait**: 2-5 minutes for npm install + - Verify: `ls -la node_modules/` (should have packages) + +- [ ] **Configure Environment** + - Copy template: `cp .env.example .env.production` + - Edit: `nano .env.production` + - Set variables: + ``` + NODE_ENV=production + PORT=9000 + MONGODB_URI=mongodb://localhost:27017/tractatus_prod + JWT_SECRET= + JWT_EXPIRY=7d + CLAUDE_API_KEY= + CLAUDE_MODEL=claude-sonnet-4-5-20250929 + ADMIN_EMAIL=john.stroh.nz@pm.me + ``` + - Secure permissions: `chmod 600 .env.production` + - **Verify**: `cat .env.production` (secrets present, file readable only by owner) + +- [ ] **Build Assets** + - Build Tailwind CSS: `npm run build:css` + - Verify: `ls -lh public/css/tailwind.css` (should be ~24KB) + +### Day 10: Database Initialization + +- [ ] **Configure MongoDB Authentication** + - Edit config: `sudo nano /etc/mongod.conf` + - Set: + ```yaml + security: + authorization: enabled + net: + bindIp: 127.0.0.1 + port: 27017 + ``` + - Restart: `sudo systemctl restart mongod` + - Verify: `sudo systemctl status mongod` (should be running) + +- [ ] **Create Database & User** + - Connect: `mongosh` + - Create user: + ```javascript + use tractatus_prod + db.createUser({ + user: 'tractatus', + pwd: '', + roles: [{ role: 'readWrite', db: 'tractatus_prod' }] + }) + ``` + - Exit: `exit` + +- [ ] **Initialize Database** + - Run migration: `npm run init:db` + - Seed admin user: `npm run seed:admin` + - **Verify**: `mongosh tractatus_prod -u tractatus -p` (should connect) + +--- + +## Week 3: Service Configuration + +### Day 11-12: Systemd Service + +- [ ] **Create Systemd Service File** + - Create: `sudo nano /etc/systemd/system/tractatus.service` + - Content: + ```ini + [Unit] + Description=Tractatus AI Safety Framework + After=network.target mongod.service + + [Service] + Type=simple + User=tractatus + WorkingDirectory=/var/www/tractatus + Environment=NODE_ENV=production + EnvironmentFile=/var/www/tractatus/.env.production + ExecStart=/usr/bin/node src/server.js + Restart=on-failure + RestartSec=10 + + [Install] + WantedBy=multi-user.target + ``` + - Reload: `sudo systemctl daemon-reload` + +- [ ] **Enable & Start Service** + - Enable: `sudo systemctl enable tractatus.service` + - Start: `sudo systemctl start tractatus.service` + - Check status: `sudo systemctl status tractatus.service` + - View logs: `sudo journalctl -u tractatus.service -f` + - **Verify**: Service running, no errors in logs + +- [ ] **Test Application** + - Test locally: `curl http://localhost:9000/health` + - **Expected**: `{"status":"healthy","database":"connected"}` + +### Day 13-14: Nginx Configuration + +- [ ] **Create Nginx Site Config** + - Create: `sudo nano /etc/nginx/sites-available/tractatus` + - Content: (Use configuration from PHASE-2-INFRASTRUCTURE-PLAN.md) + - Enable site: `sudo ln -s /etc/nginx/sites-available/tractatus /etc/nginx/sites-enabled/` + - Remove default: `sudo rm /etc/nginx/sites-enabled/default` + +- [ ] **Test Nginx Configuration** + - Test config: `sudo nginx -t` + - **Expected**: "syntax is ok", "test is successful" + +- [ ] **Reload Nginx** + - Reload: `sudo systemctl reload nginx` + - Check status: `sudo systemctl status nginx` + - **Verify**: Nginx running, no errors + +### Day 15: SSL/TLS Setup + +- [ ] **Obtain Let's Encrypt Certificate** + - Run Certbot: `sudo certbot --nginx -d agenticgovernance.digital -d www.agenticgovernance.digital` + - Enter email: john.stroh.nz@pm.me + - Agree to terms: Y + - Share email: N (optional) + - Redirect HTTP to HTTPS: Y (option 2) + - **Wait**: Certificate issuance (30-60 seconds) + +- [ ] **Verify SSL Certificate** + - Test HTTPS: `curl https://agenticgovernance.digital/health` + - Browser test: Open https://agenticgovernance.digital + - SSL Labs test: https://www.ssllabs.com/ssltest/ (should be A+) + +- [ ] **Test Auto-Renewal** + - Dry run: `sudo certbot renew --dry-run` + - **Expected**: "Congratulations, all renewals succeeded" + - Verify timer: `sudo systemctl list-timers | grep certbot` + +--- + +## Week 4: Monitoring & Testing + +### Day 16-17: Logging & Monitoring + +- [ ] **Configure Log Rotation** + - Create: `sudo nano /etc/logrotate.d/tractatus` + - Content: + ``` + /var/log/tractatus/*.log { + daily + rotate 7 + compress + delaycompress + missingok + notifempty + create 0640 tractatus tractatus + } + ``` + - Test: `sudo logrotate -f /etc/logrotate.d/tractatus` + +- [ ] **Create Healthcheck Script** + - Create: `sudo nano /usr/local/bin/tractatus-healthcheck.sh` + - Content: (Use script from PHASE-2-INFRASTRUCTURE-PLAN.md) + - Make executable: `sudo chmod +x /usr/local/bin/tractatus-healthcheck.sh` + - Test: `/usr/local/bin/tractatus-healthcheck.sh` + +- [ ] **Configure Cron for Monitoring** + - Edit crontab: `sudo crontab -e` + - Add: `*/5 * * * * /usr/local/bin/tractatus-healthcheck.sh` + - Verify: `sudo crontab -l` + +### Day 18-19: Backup Configuration + +- [ ] **Create Backup Script** + - Create: `nano ~/backup-mongodb.sh` + - Content: (Use script from PHASE-2-INFRASTRUCTURE-PLAN.md) + - Make executable: `chmod +x ~/backup-mongodb.sh` + - Test: `./backup-mongodb.sh` + - Verify: `ls -lh /var/backups/tractatus/mongodb/` + +- [ ] **Schedule Daily Backups** + - Edit crontab: `crontab -e` + - Add: `0 2 * * * /home/tractatus/backup-mongodb.sh >> /var/log/tractatus/backup.log 2>&1` + - Verify: `crontab -l` + +### Day 20-21: Production Testing + +- [ ] **Smoke Tests** + - Homepage: https://agenticgovernance.digital/ + - Docs viewer: https://agenticgovernance.digital/docs-viewer.html + - API health: https://agenticgovernance.digital/health + - Admin login: https://agenticgovernance.digital/admin/login.html + - Researcher path: https://agenticgovernance.digital/researcher.html + - Implementer path: https://agenticgovernance.digital/implementer.html + - Advocate path: https://agenticgovernance.digital/advocate.html + - **Verify**: All pages load, no console errors + +- [ ] **Performance Testing** + - Lighthouse audit: Run from Chrome DevTools + - Target: Performance >90, Accessibility 100, Best Practices 100, SEO >90 + - WebPageTest: https://www.webpagetest.org + - Target: <3s load time (95th percentile) + +- [ ] **Security Testing** + - SSL Labs: https://www.ssllabs.com/ssltest/ + - Target: A+ rating + - Security Headers: https://securityheaders.com + - Target: A rating + - CSP check: Browser console (no violations) + +**Milestone 1 Complete**: ✅ Infrastructure deployed, site live at https://agenticgovernance.digital + +--- + +## Week 5-8: AI Features Implementation + +### Week 5: Claude API Integration + +- [ ] **API Key Configuration** + - Add to .env.production: `CLAUDE_API_KEY=` + - Restart service: `sudo systemctl restart tractatus.service` + - **Verify**: No errors in logs + +- [ ] **Rate Limiting Setup** + - Configure in ClaudeAPI.service.js: + - Requests/minute: 60 + - Tokens/day: 500,000 + - Monthly budget: $200 + - Test limits: (unit test) + +- [ ] **Cost Monitoring** + - Create dashboard view: /admin/api-usage + - Show: tokens used today, cost estimate, budget remaining + - Alert threshold: 80% of monthly budget + - **Test**: View dashboard, verify metrics + +### Week 6: Blog Curation System + +- [ ] **Blog Database Schema** + - Create BlogPost model: src/models/BlogPost.model.js + - Fields: title, slug, content, author, published_at, ai_assisted, etc. + - Indexes: slug (unique), published_at, category + +- [ ] **Topic Suggestion Pipeline** + - Implement: src/services/BlogCuration.service.js + - Method: suggestTopics(newsFeeds) → topics[] + - Test: Generate 5-10 topics from mock data + +- [ ] **Outline Generation** + - Method: generateOutline(topic) → outline + - Test: Generate outline for approved topic + +- [ ] **Blog UI** + - Create: public/blog/index.html (list view) + - Create: public/blog/[slug].html (single post view) + - Create: public/blog/feed.xml (RSS) + - **Test**: View blog list, single post, RSS feed + +- [ ] **Seed Content** (3-5 posts) + - Post 1: "Introducing the Tractatus Framework" + - Post 2: "The 27027 Incident: A Case Study" + - Post 3: "Why AI Safety Needs Architecture" + - Post 4: "Boundary Enforcement in Practice" + - Post 5: "Human Oversight: Not Optional" + - **Publish**: All posts live on blog + +### Week 7: Media Inquiry Triage + +- [ ] **Media Inquiry Form** + - Create: public/contact.html + - Fields: name, email, organization, message, type (press/academic/commercial) + - Validation: Required fields, email format + +- [ ] **AI Classification** + - Implement: src/services/MediaTriage.service.js + - Method: classifyInquiry(text) → {category, priority, confidence} + - Test: Classify sample inquiries + +- [ ] **Priority Scoring** + - Method: calculatePriority(inquiry) → score (0.0-1.0) + - Factors: reach, relevance, urgency, alignment + - Test: Verify scores for sample inquiries + +- [ ] **Draft Response Generation** + - Method: generateDraft(inquiry, category) → draft + - Templates: Press, Academic, Commercial, Community + - Test: Generate drafts for each category + +- [ ] **Admin Triage Dashboard** + - View: /admin/media-triage + - Features: List inquiries, view AI analysis, approve/edit/reject drafts + - **Test**: Submit inquiry, review in dashboard + +### Week 8: Case Study Portal + +- [ ] **Case Study Form** + - Create: public/submit-case-study.html + - Fields: title, summary, date, AI system, source URL, failure mode, description, consent + - Validation: Required fields, URL format, consent checkbox + +- [ ] **AI Relevance Analysis** + - Implement: src/services/CaseStudyAnalysis.service.js + - Method: assessRelevance(submission) → {relevant, confidence, reasoning} + - Test: Analyze sample submissions + +- [ ] **Tractatus Mapping** + - Method: mapToFramework(submission) → {components[], prevention_strategy} + - Test: Map sample failures to framework components + +- [ ] **Moderation Queue** + - View: /admin/case-studies + - Features: List submissions, view AI analysis, approve/reject/request changes + - **Test**: Submit case study, review in queue + +- [ ] **Public Case Study Viewer** + - Create: public/case-studies/index.html (list) + - Create: public/case-studies/[slug].html (single) + - **Test**: View published case studies + +- [ ] **Seed Case Studies** (3-5 examples) + - Case 1: "The 27027 Incident" (instruction override) + - Case 2: "ChatGPT Medical Hallucination" (boundary violation) + - Case 3: "GitHub Copilot Code Injection" (context pressure) + - Case 4: "Bing Chat Sydney Persona" (metacognitive failure) + - Case 5: "Jasper AI Copyright Violation" (boundary violation) + - **Publish**: All case studies live + +**Milestone 2 Complete**: ✅ All AI features operational, human oversight enforced + +--- + +## Week 9-10: Polish & Testing + +### Week 9: Governance Audit + +- [ ] **Review All AI Prompts** + - Blog topic suggestion prompt: Aligned with TRA-OPS-0002? ___ + - Blog outline prompt: Aligned with TRA-OPS-0002? ___ + - Media classification prompt: Aligned with TRA-OPS-0003? ___ + - Case study analysis prompt: Aligned with TRA-OPS-0004? ___ + - **Action**: Update prompts if needed + +- [ ] **Test Boundary Enforcement** + - Attempt to auto-publish blog post (should FAIL) ___ + - Attempt to auto-send media response (should FAIL) ___ + - Attempt to auto-publish case study (should FAIL) ___ + - **Verify**: All blocked by BoundaryEnforcer + +- [ ] **Audit Trail Verification** + - Check database: All AI decisions logged? ___ + - Fields present: input, output, human_decision, reviewer, timestamp? ___ + - Retention: 2-year policy documented? ___ + +### Week 10: End-to-End Testing + +- [ ] **User Journey Testing** + - Journey 1: Researcher explores docs, views demos, submits feedback + - Journey 2: Implementer reviews API docs, tests integration, submits case study + - Journey 3: Advocate reads blog, understands principles, shares on social media + - **Verify**: All journeys complete without errors + +- [ ] **Mobile Testing** + - Test on iPhone (Safari) + - Test on Android (Chrome) + - Verify: Responsive design, readable text, functional buttons + - **Target**: All pages usable on mobile + +- [ ] **Browser Compatibility** + - Test on Chrome (latest) + - Test on Firefox (latest) + - Test on Safari (latest) + - Test on Edge (latest) + - **Verify**: No console errors, all features work + +- [ ] **Accessibility Re-Audit** + - Run WAVE: https://wave.webaim.org + - Run Lighthouse: Accessibility score 100 + - Manual keyboard navigation: All interactive elements accessible + - Screen reader test: NVDA or VoiceOver + - **Target**: WCAG AA compliant + +- [ ] **Load Testing** + - Tool: k6 or Artillery + - Scenario: 100 concurrent users, 5-minute test + - Metrics: Response time <3s, error rate <1% + - **Verify**: System handles load without degradation + +--- + +## Week 11-12: Soft Launch + +### Week 11: Launch Preparation + +- [ ] **Finalize Soft Launch List** + - Identify 8-12 researchers (names + emails) + - Identify 8-12 implementers (names + emails) + - Identify 4-6 advocates (names + emails) + - **Total**: 20-30 users + +- [ ] **Create Feedback Survey** + - Tool: Google Forms or TypeForm + - Questions: (Use template from PHASE-2-EMAIL-TEMPLATES.md) + - Test: Complete survey yourself, verify all questions work + - **Link**: _________________________ + +- [ ] **Prepare Invitation Emails** + - Personalize Template A (Researcher) for each researcher + - Personalize Template B (Implementer) for each implementer + - Personalize Template C (Advocate) for each advocate + - **Review**: All names correct, specific reasons included + +- [ ] **Platform Final Check** + - All blog posts published? ___ + - All case studies published? ___ + - All demos working? ___ + - Feedback form linked? ___ + - No broken links? ___ + - **Status**: Ready for users + +### Week 12: Launch & Feedback + +- [ ] **Send Invitations** + - Send all emails (BCC for privacy) + - Track: Spreadsheet with sent date, opened (if tracked), responded + - **Date sent**: _____________ + +- [ ] **Monitor Platform** + - Daily: Check server logs for errors + - Daily: Review uptime monitoring (target: 99%+) + - Daily: Check feedback form responses + - **Action**: Respond to issues within 24 hours + +- [ ] **Respond to Feedback** + - Thank all respondents within 48 hours + - Address critical issues immediately + - Log all feedback themes in spreadsheet + - **Target**: >30% response rate (9+ responses from 30 invitations) + +- [ ] **Follow-Up Reminders** + - Week 1: Send reminder (Template E) + - Week 2: Send final reminder (Template G) + - **Track**: Response rate after each reminder + +- [ ] **Compile Feedback Report** + - Themes: What users liked, what confused them, what's missing + - Quantitative: Satisfaction scores, recommendation rate + - Action items: Prioritized list of improvements + - **Share**: Email summary to all participants + +**Milestone 3 Complete**: ✅ Soft launch complete, feedback collected + +--- + +## Post-Phase 2: Transition to Phase 3 + +### Evaluation + +- [ ] **Review Success Criteria** + - Technical success: Uptime 99%+, performance <3s, zero vulnerabilities ___ + - Governance success: 100% human approval, zero violations ___ + - User success: 20-50 users, 4+/5 rating, 50+ readers/post ___ + - Business success: Costs <$150/month, zero breaches ___ + +- [ ] **Decision: Proceed to Phase 3?** + - All criteria met? ___ + - Critical bugs resolved? ___ + - Positive user feedback? ___ + - John Stroh approval? ___ + - **Decision**: GO / NO-GO / EXTEND + +### Knowledge Transfer + +- [ ] **Document Lessons Learned** + - What went well? ___ + - What didn't go well? ___ + - What would we do differently? ___ + - **Action**: Create Phase 2 retrospective document + +- [ ] **Update Documentation** + - Update CLAUDE.md with Phase 2 completion + - Update README.md if needed + - Archive planning documents + - **Status**: Documentation current + +### Handoff (if hiring admin reviewer) + +- [ ] **Admin Onboarding** + - Share TRA-OPS-* governance documents + - Train on moderation workflows + - Grant access to admin dashboard + - Shadow for 2 weeks + - **Status**: Admin ready for independent work + +--- + +## Emergency Contacts + +**Server Issues**: +- OVHCloud Support: support.ovh.com +- Server IP: ___.___.___.___ +- SSH: `ssh tractatus@` + +**API Issues**: +- Anthropic Support: support@anthropic.com +- API Dashboard: https://console.anthropic.com + +**Domain/DNS Issues**: +- OVHCloud DNS: ovh.com (control panel) +- DNS Checker: https://dnschecker.org + +**Security Incidents**: +- Immediate: `sudo systemctl stop tractatus.service` (shut down application) +- Review logs: `sudo journalctl -u tractatus.service -n 1000` +- Contact: John Stroh (john.stroh.nz@pm.me) + +--- + +## Progress Tracking + +**Week-by-Week Summary**: + +| Week | Focus | Status | Notes | +|------|-------|--------|-------| +| 0 | Pre-Kickoff | ☐ | Administrative setup, accounts | +| 1 | Infrastructure | ☐ | Server provisioning, security | +| 2 | Deployment | ☐ | DNS, app code, database | +| 3 | Services | ☐ | Systemd, Nginx, SSL | +| 4 | Monitoring | ☐ | Logs, backups, testing | +| 5 | Claude API | ☐ | Integration, rate limits | +| 6 | Blog System | ☐ | Curation pipeline, seed content | +| 7 | Media Triage | ☐ | Forms, classification, dashboard | +| 8 | Case Studies | ☐ | Submissions, analysis, moderation | +| 9 | Governance | ☐ | Audit, boundary tests | +| 10 | Testing | ☐ | E2E, mobile, accessibility | +| 11 | Prep Launch | ☐ | User list, survey, emails | +| 12 | Soft Launch | ☐ | Send invitations, collect feedback | + +**Completion Percentage**: ___% (update weekly) + +--- + +## Revision History + +| Date | Version | Changes | +|------|---------|---------| +| 2025-10-07 | 1.0 | Initial Phase 2 kickoff checklist | + +--- + +**Checklist Owner**: John Stroh +**Last Updated**: 2025-10-07 +**Next Review**: Weekly during Phase 2 execution diff --git a/docs/PHASE-2-PREPARATION-ADVISORY.md b/docs/PHASE-2-PREPARATION-ADVISORY.md new file mode 100644 index 00000000..c05f085d --- /dev/null +++ b/docs/PHASE-2-PREPARATION-ADVISORY.md @@ -0,0 +1,604 @@ +# Phase 2 Preparation Advisory + +**Project**: Tractatus AI Safety Framework +**Domain**: agenticgovernance.digital +**Objective**: World-Class UI/UX +**Status**: Pre-Deployment Recommendations +**Prepared**: 2025-10-07 + +--- + +## Table of Contents + +1. [UI/UX Excellence Preparation](#uiux-excellence-preparation) +2. [Design System Documentation](#design-system-documentation) +3. [Performance Optimization](#performance-optimization) +4. [Accessibility Excellence](#accessibility-excellence) +5. [Domain Migration Checklist](#domain-migration-checklist) +6. [Security & Privacy](#security--privacy) +7. [Content Readiness](#content-readiness) +8. [Monitoring & Analytics](#monitoring--analytics) +9. [User Testing Protocol](#user-testing-protocol) +10. [Final Pre-Deployment Checklist](#final-pre-deployment-checklist) + +--- + +## UI/UX Excellence Preparation + +### World-Class UI/UX Standards + +**Benchmark Sites**: Stripe Docs, Tailwind CSS Docs, Anthropic Claude Docs, Linear App + +**Core Principles**: +1. **Clarity over cleverness**: Users understand immediately what the framework does +2. **Speed**: Perceived performance matters more than measured performance +3. **Consistency**: Every interaction follows predictable patterns +4. **Accessibility**: WCAG AAA aspirational (AA minimum achieved) +5. **Delight**: Subtle animations, thoughtful micro-interactions +6. **Trust**: Professional, credible, transparent design + +### Recommended Actions + +**Before Deployment**: +- [ ] Create comprehensive design system document (colors, typography, spacing, components) +- [ ] Document component patterns (buttons, cards, modals, forms) +- [ ] Define animation/transition standards (durations, easing functions) +- [ ] Create UI component library reference page +- [ ] Design mobile-first responsive breakpoints (documented) + +**During Soft Launch**: +- [ ] Conduct user testing sessions (5-10 users from each audience) +- [ ] Track Core Web Vitals (LCP, FID, CLS) +- [ ] Gather qualitative feedback (usability, clarity, trust) +- [ ] A/B test key flows (researcher path vs. implementer path) + +--- + +## Design System Documentation + +### Create: `/docs/DESIGN-SYSTEM.md` + +**Content to Document**: + +#### Color Palette +```css +/* Primary Colors */ +--blue-600: #2563eb; /* Primary CTA */ +--blue-700: #1d4ed8; /* Hover states */ +--purple-700: #7c3aed; /* Accents */ + +/* Semantic Colors */ +--success: #10b981; /* Approvals, success states */ +--warning: #f59e0b; /* Warnings, pending states */ +--error: #ef4444; /* Errors, rejections */ +--info: #3b82f6; /* Information, tips */ + +/* Neutrals */ +--gray-50 through --gray-900 (full Tailwind scale) +``` + +#### Typography Scale +```css +/* Headings */ +h1: 2.5rem (40px), font-bold, line-height 1.2 +h2: 2rem (32px), font-bold, line-height 1.3 +h3: 1.5rem (24px), font-semibold, line-height 1.4 +h4: 1.25rem (20px), font-semibold, line-height 1.5 + +/* Body */ +body: 1rem (16px), font-normal, line-height 1.6 +small: 0.875rem (14px), font-normal, line-height 1.5 +``` + +#### Spacing System +``` +4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px, 96px +(Tailwind's 1, 2, 3, 4, 6, 8, 12, 16, 24 scale) +``` + +#### Component Patterns +- **Buttons**: Primary, Secondary, Outline, Ghost, sizes (sm, md, lg) +- **Cards**: Default, Hover, Interactive, Stat cards +- **Forms**: Input, Textarea, Select, Checkbox, Radio +- **Modals**: Center, Slide-over, Confirmation dialogs +- **Notifications**: Toast, Banner, Inline alerts + +#### Animation Standards +```css +/* Transitions */ +--transition-fast: 150ms ease-in-out; +--transition-base: 200ms ease-in-out; +--transition-slow: 300ms ease-in-out; + +/* Easing */ +--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1); +--ease-out: cubic-bezier(0, 0, 0.2, 1); +``` + +**Action**: Create this document before Week 5 (AI features). Use it to guide all UI implementation. + +--- + +## Performance Optimization + +### Target Metrics (World-Class Standards) + +| Metric | Target | Current | Status | +|--------|--------|---------|--------| +| **Largest Contentful Paint (LCP)** | <2.5s | ~1.8s | ✅ Good | +| **First Input Delay (FID)** | <100ms | ~50ms | ✅ Good | +| **Cumulative Layout Shift (CLS)** | <0.1 | ~0.05 | ✅ Good | +| **Time to First Byte (TTFB)** | <600ms | TBD | 🔄 Test | +| **Total Page Size** | <1MB | ~400KB | ✅ Good | +| **JavaScript Bundle Size** | <200KB | ~180KB | ✅ Good | + +### Optimization Checklist + +**Pre-Deployment**: +- [ ] Enable Brotli compression on Nginx +- [ ] Configure HTTP/2 (automatic with Nginx + SSL) +- [ ] Set aggressive caching headers for static assets (1 year) +- [ ] Minify CSS and JavaScript (production build) +- [ ] Optimize images (WebP format, lazy loading) +- [ ] Preload critical assets (fonts, hero images) +- [ ] Implement service worker for offline support (Phase 3) + +**Server-Side Optimizations**: +- [ ] Enable MongoDB query caching +- [ ] Implement Redis for session storage (Phase 3) +- [ ] Use CDN for static assets (Cloudflare bot protection only, or skip CDN entirely) +- [ ] Configure connection pooling for MongoDB +- [ ] Enable Nginx gzip/Brotli compression + +**Frontend Optimizations**: +- [ ] Code splitting for demos (load on demand) +- [ ] Lazy load images below fold +- [ ] Defer non-critical JavaScript +- [ ] Inline critical CSS (above-the-fold) +- [ ] Use font-display: swap for web fonts + +**Monitoring**: +- [ ] Set up Lighthouse CI in GitHub Actions +- [ ] Configure Core Web Vitals monitoring (Google Analytics or Plausible) +- [ ] Weekly performance audits during soft launch + +--- + +## Accessibility Excellence + +### WCAG AAA Aspirational Checklist + +**Level AA (Achieved)**: +- ✅ Semantic HTML (`
`, `
`, `