From 90d3db31deb4974dd42338547852d71da5cc1f04 Mon Sep 17 00:00:00 2001 From: TheFlow Date: Sun, 12 Oct 2025 17:09:00 +1300 Subject: [PATCH] security: remove sensitive internal documentation from public repository MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removed 16 sensitive files from git tracking to protect internal processes: Root directory (5 files): - CLAUDE_Tractatus_Maintenance_Guide.md - DEPLOYMENT-2025-10-08.md - NEXT_SESSION.md - NEXT_SESSION_OPENING_PROMPT.md - SESSION_CLOSEDOWN_20251006.md docs/ directory (11 files): - KOHA_PRODUCTION_DEPLOYMENT.md - PHASE-2-DEPLOYMENT-GUIDE.md - PRODUCTION_DEPLOYMENT_CHECKLIST.md - SESSION-2025-10-07-AI-FEATURES.md - SESSION-HANDOFF-2025-10-12.md - SESSION_HANDOFF_2025-10-10.md - SESSION_HANDOFF_2025-10-11.md - SESSION_HANDOFF_2025_10_11.md - SESSION_HANDOFF_2025_10_11_P3_P4.md - SESSION_INIT_API_MEMORY_AUDIT.md - planning/PHASE_3_SESSION_1_SUMMARY.md These files contain: - Internal workflow documentation - Deployment procedures and server details - Session handoff information - Planning and strategy documents Security posture: ✅ Files removed from tracking (won't appear in new commits) ✅ Files remain on disk for local use ✅ .gitignore already blocks these patterns ✅ .rsyncignore blocks deployment to production ⚠️ Files remain in git history (accessible via git log) Note: This is low-risk remediation. Files remain in history but won't be visible in file browser or future commits. For complete removal, git history rewrite would be needed (high risk, requires force push). Risk assessment: Medium exposure (internal processes visible) but no credentials, keys, or direct access information exposed. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE_Tractatus_Maintenance_Guide.md | 827 ----------- DEPLOYMENT-2025-10-08.md | 284 ---- NEXT_SESSION.md | 386 ----- NEXT_SESSION_OPENING_PROMPT.md | 190 --- SESSION_CLOSEDOWN_20251006.md | 453 ------ docs/KOHA_PRODUCTION_DEPLOYMENT.md | 540 ------- docs/PHASE-2-DEPLOYMENT-GUIDE.md | 1567 -------------------- docs/PRODUCTION_DEPLOYMENT_CHECKLIST.md | 676 --------- docs/SESSION-2025-10-07-AI-FEATURES.md | 450 ------ docs/SESSION-HANDOFF-2025-10-12.md | 409 ----- docs/SESSION_HANDOFF_2025-10-10.md | 469 ------ docs/SESSION_HANDOFF_2025-10-11.md | 736 --------- docs/SESSION_HANDOFF_2025_10_11.md | 769 ---------- docs/SESSION_HANDOFF_2025_10_11_P3_P4.md | 676 --------- docs/SESSION_INIT_API_MEMORY_AUDIT.md | 306 ---- docs/planning/PHASE_3_SESSION_1_SUMMARY.md | 414 ------ 16 files changed, 9152 deletions(-) delete mode 100644 CLAUDE_Tractatus_Maintenance_Guide.md delete mode 100644 DEPLOYMENT-2025-10-08.md delete mode 100644 NEXT_SESSION.md delete mode 100644 NEXT_SESSION_OPENING_PROMPT.md delete mode 100644 SESSION_CLOSEDOWN_20251006.md delete mode 100644 docs/KOHA_PRODUCTION_DEPLOYMENT.md delete mode 100644 docs/PHASE-2-DEPLOYMENT-GUIDE.md delete mode 100644 docs/PRODUCTION_DEPLOYMENT_CHECKLIST.md delete mode 100644 docs/SESSION-2025-10-07-AI-FEATURES.md delete mode 100644 docs/SESSION-HANDOFF-2025-10-12.md delete mode 100644 docs/SESSION_HANDOFF_2025-10-10.md delete mode 100644 docs/SESSION_HANDOFF_2025-10-11.md delete mode 100644 docs/SESSION_HANDOFF_2025_10_11.md delete mode 100644 docs/SESSION_HANDOFF_2025_10_11_P3_P4.md delete mode 100644 docs/SESSION_INIT_API_MEMORY_AUDIT.md delete mode 100644 docs/planning/PHASE_3_SESSION_1_SUMMARY.md diff --git a/CLAUDE_Tractatus_Maintenance_Guide.md b/CLAUDE_Tractatus_Maintenance_Guide.md deleted file mode 100644 index 56b4a41a..00000000 --- a/CLAUDE_Tractatus_Maintenance_Guide.md +++ /dev/null @@ -1,827 +0,0 @@ -# Tractatus - Claude Code Maintenance Guide - -**Comprehensive reference for Claude Code sessions on the Tractatus project** - -**Last Updated**: 2025-10-08 -**Version**: 2.0.0 (Enforcement-First Architecture) - ---- - -## Table of Contents - -1. [Project Identity](#project-identity) -2. [Tractatus Framework Governance](#tractatus-framework-governance) -3. [Session Management](#session-management) -4. [Development Conventions](#development-conventions) -5. [Directory Structure](#directory-structure) -6. [Phase 1 Deliverables](#phase-1-deliverables) -7. [Human Approval Requirements](#human-approval-requirements) -8. [Te Tiriti & Indigenous Perspective](#te-tiriti--indigenous-perspective) -9. [Links & References](#links--references) - ---- - -## Project Identity - -### Core Information -- **Project Name**: Tractatus Website Platform -- **Domain**: agenticgovernance.digital -- **Repository**: GitHub (primary) + Codeberg/Gitea (mirrors) -- **Status**: Development - Phase 1 Implementation -- **Created**: 2025-10-06 -- **Primary Developer**: Claude Code (Anthropic Sonnet 4.5) -- **Project Owner**: John Stroh - -### ⚠️ Critical: Project Isolation - -**THIS IS A SEPARATE PROJECT FROM family-history AND sydigital** - -- **Separate MongoDB instance**: Port 27017, database `tractatus_dev` -- **Separate application port**: 9000 -- **Separate Git repository**: Local + GitHub account -- **Separate systemd services**: mongodb-tractatus.service, tractatus.service -- **No shared code/data**: Patterns may be adapted, but no dependencies - -**Sessions must maintain clear separation.** Always verify which project context you're in. - -### Project Purpose - -Build a world-class platform demonstrating the **Tractatus-Based LLM Safety Framework** through: - -1. **Three Audience Paths**: Researcher, Implementer, Advocate -2. **AI-Powered Features**: Blog curation, media triage, case studies (all with human oversight) -3. **Interactive Demonstrations**: Classification, 27027 incident, boundary enforcement -4. **Dogfooding**: The website implements Tractatus to govern its own AI operations -5. **Values Alignment**: Sovereignty, Transparency, Harmlessness, Community - -**Timeline**: 3-4 months for complete Phase 1 local prototype (no rush, no shortcuts, world-class quality) - -### Technical Architecture - -#### Infrastructure -- **MongoDB**: Port 27017, database `tractatus_dev` -- **Application**: Node.js/Express on port 9000 -- **WebSocket**: Port 9001 (if needed) -- **Data Directory**: `/home/theflow/projects/tractatus/data/mongodb` -- **Logs**: `/home/theflow/projects/tractatus/logs/` - -#### Technology Stack -- **Backend**: Node.js 18+, Express 4.x, MongoDB 7+ -- **Frontend**: Vanilla JavaScript, Tailwind CSS (no framework dependency) -- **Authentication**: JWT for admin/moderation -- **AI Integration**: Claude API (Sonnet 4.5) - Phase 2+ -- **File Storage**: GridFS for PDFs, documents -- **Testing**: Jest + Supertest - -#### Database Collections -```javascript -tractatus_dev.documents // Technical papers, framework docs -tractatus_dev.blog_posts // AI-curated, human-approved -tractatus_dev.media_inquiries // Press/media with AI triage -tractatus_dev.case_submissions // Community case studies -tractatus_dev.resources // External links, aligned projects -tractatus_dev.moderation_queue // Human oversight queue -tractatus_dev.users // Admin accounts -tractatus_dev.citations // Academic citation tracking -tractatus_dev.translations // Multi-language content (future) -tractatus_dev.koha_donations // Phase 3 -``` - ---- - -## Tractatus Framework Governance - -### Core Services - Six Mandatory Components - -**All six MUST be active throughout every session. Framework fade = critical failure.** - -### What is a "27027 Failure"? - -Named after the port number 27027 from an October 2025 incident: - -**User instruction**: "Check port 27027" (explicit, non-standard MongoDB port) -**Claude's action**: Used port 27017 (standard default) -**Root cause**: Pattern recognition bias - training data's "MongoDB = 27017" association overrode explicit instruction **immediately** - -**Key insight**: This is NOT about forgetting. Claude never truly "heard" the instruction because the learned pattern was so strong it **autocorrected** the explicit input, like a spell-checker changing a deliberately unusual word. - -**Why this matters**: As AI capabilities increase, training data creates stronger patterns, making this problem WORSE, not better. The framework must architecturally prevent pattern recognition from overriding explicit human instructions. - ---- - -#### 1. ContextPressureMonitor -**Purpose**: Session quality management through multi-factor pressure analysis - -**When to invoke**: -- Session start (baseline: 0/200000 tokens) -- Every 25% tokens (50k, 100k, 150k) -- After complex multi-file operations -- After any error or unexpected behavior -- Every ~20 messages or 40k tokens - -**Pressure Levels**: - -| Level | Score | Action | What to Do | -|-------|-------|--------|------------| -| **NORMAL** | 0-30% | PROCEED | Continue normally | -| **ELEVATED** | 30-50% | INCREASE_VERIFICATION | More careful, verify outputs | -| **HIGH** | 50-70% | SUGGEST_CONTEXT_REFRESH | Consider session handoff | -| **CRITICAL** | 70-85% | MANDATORY_VERIFICATION | Verify all actions, prepare handoff | -| **DANGEROUS** | 85%+ | IMMEDIATE_HALT | Stop, create handoff, refresh context | - -**Monitored Factors** (Weighted): -1. **Token Usage** (35% weight) - Context window pressure -2. **Conversation Length** (25% weight) - Attention decay over long sessions -3. **Task Complexity** (15% weight) - Number of simultaneous tasks, dependencies, file modifications -4. **Error Frequency** (15% weight) - Recent errors indicate degraded state -5. **Instruction Density** (10% weight) - Too many competing directives - -**Command**: -```bash -node scripts/check-session-pressure.js --tokens / --messages --tasks --errors -``` - -**Files updated**: -- `.claude/session-state.json` (last_framework_activity.ContextPressureMonitor) -- `.claude/token-checkpoints.json` (completed checkpoints) - -#### 2. InstructionPersistenceClassifier -**Purpose**: Make explicit instructions override learned patterns to prevent 27027 failures (pattern recognition bias) - -**When to invoke**: -- User gives explicit instruction -- Configuration specifications -- Architectural constraints -- Port/database requirements -- Coding standards -- Project-specific rules - -**Quadrant Mapping**: - -| Function | Quadrant | Human Oversight | Example | -|----------|----------|-----------------|---------| -| Mission/values changes | STRATEGIC | Mandatory approval | "Always prioritize privacy" | -| Blog editorial guidelines | OPERATIONAL | Quarterly review | "All posts must cite sources" | -| Publish approved post | TACTICAL | Pre-approved | Execute after human approval | -| Technical config | SYSTEM | Technical review | MongoDB ports, API keys | -| AI suggests blog topics | STOCHASTIC | Always human approval | "Write about GDPR" | - -**Classification process**: -1. Identify explicit instruction from user -2. Classify quadrant (STR/OPS/TAC/SYS/STO) -3. Determine persistence level (LOW/MEDIUM/HIGH/CRITICAL) -4. Assign temporal scope (SESSION/SPRINT/PROJECT/PERMANENT) -5. Set verification requirement (NONE/ADVISORY/MANDATORY) -6. Calculate explicitness score (0.0-1.0) -7. Store in `.claude/instruction-history.json` - -**Files updated**: -- `.claude/instruction-history.json` (append new instruction) -- `.claude/session-state.json` (last_framework_activity.InstructionPersistenceClassifier) - -#### 3. CrossReferenceValidator -**Purpose**: Validate proposed actions against instruction history to prevent conflicts - -**When to invoke**: -- Before database schema changes -- Before configuration modifications -- Before architectural decisions -- Before changing established patterns -- Before modifying system-level settings - -**Validation process**: -1. Load `.claude/instruction-history.json` -2. Identify relevant instructions (by quadrant, scope, keywords) -3. Check for conflicts with proposed action -4. If HIGH/CRITICAL persistence conflicts: BLOCK action -5. Report conflicts to user with instruction details -6. Require user override for conflicting actions - -**Blocking criteria**: -- HIGH persistence instruction + direct conflict = BLOCK -- CRITICAL persistence instruction + any conflict = BLOCK -- MANDATORY verification required + no verification = BLOCK - -**Files updated**: -- `.claude/session-state.json` (last_framework_activity.CrossReferenceValidator) - -#### 4. BoundaryEnforcer -**Purpose**: Ensure AI never makes values decisions without human approval - -**When to invoke**: -- Before privacy policy decisions -- Before ethical trade-off decisions -- Before user agency changes -- Before mission/values modifications -- Before governance document changes - -**Values boundaries** (from Tractatus framework): -- Privacy vs. performance trade-offs -- User autonomy vs. safety -- Transparency vs. security -- Community vs. individual rights -- Indigenous sovereignty vs. technical expediency - -**Enforcement actions**: -1. Detect values-sensitive decision domain -2. Report boundary violation to user -3. BLOCK automatic decision -4. Provide alternatives/research/analysis only -5. Require explicit human decision -6. Document decision in instruction history - -**Files updated**: -- `.claude/session-state.json` (last_framework_activity.BoundaryEnforcer) - -#### 5. MetacognitiveVerifier -**Purpose**: AI self-checks reasoning before proposing complex actions - -**When to invoke** (selective use): -- Operations with >3 file modifications -- Operations with >5 sequential steps -- Architecture changes (structural modifications) -- Security implementations -- Complex refactoring -- Multi-system integrations - -**Verification dimensions**: -1. **Alignment** (0.0-1.0): Does action align with project goals? -2. **Coherence** (0.0-1.0): Is reasoning internally consistent? -3. **Completeness** (0.0-1.0): Are edge cases considered? -4. **Safety** (0.0-1.0): What are the risks? -5. **Alternatives** (0.0-1.0): Have alternatives been explored? - -**Overall Confidence**: -- 0.90-1.0: HIGH - Proceed -- 0.75-0.89: MEDIUM - Proceed with caution -- 0.60-0.74: LOW - Reconsider approach -- <0.60: VERY LOW - Stop and rethink - -**Files updated**: -- `.claude/session-state.json` (last_framework_activity.MetacognitiveVerifier) - -#### 6. PluralisticDeliberationOrchestrator -**Purpose**: Facilitate multi-stakeholder deliberation across plural moral values without imposing hierarchy - -**When to invoke**: -- BoundaryEnforcer flags values decision (triggers deliberation) -- Stakeholder value conflict identified -- Privacy vs. safety trade-offs -- Individual rights vs. collective welfare tensions -- Cultural values conflicts (Western vs. Indigenous, secular vs. religious) -- Policy decisions affecting diverse communities - -**Core Functions**: - -**1. Values Conflict Detection** -```javascript -const conflict = await PluralisticDeliberationOrchestrator.analyzeConflict({ - decision: "Disclose user data to prevent harm?", - context: { urgency, scale, affected_groups } -}); - -// Output: -{ - moral_frameworks_in_tension: [ - { framework: "Rights-based (Deontological)", position: "...", stakeholders: [...] }, - { framework: "Consequentialist (Utilitarian)", position: "...", stakeholders: [...] }, - { framework: "Care Ethics", position: "...", stakeholders: [...] } - ], - value_trade_offs: ["Privacy vs. Safety", "Individual rights vs. Collective welfare"], - affected_stakeholder_groups: ["users_with_data", "potential_victims", "platform_community"] -} -``` - -**2. Stakeholder Engagement** -- Identify representatives from each moral framework -- Ensure diverse perspectives (not just dominant groups) -- Include affected parties (not just experts) -- Use AdaptiveCommunicationOrchestrator for culturally appropriate outreach - -**3. Deliberation Facilitation** -- Round 1: Each perspective states position -- Round 2: Identify shared values -- Round 3: Explore compromise/accommodation -- Round 4: Clarify irreconcilable differences -- Document process: NOT majority vote, BUT structured consensus-seeking with documented dissent - -**4. Outcome Documentation** -```javascript -{ - decision_made: "Disclose data in this case", - values_prioritized: ["harm_prevention", "collective_safety"], - values_deprioritized: ["individual_privacy", "data_autonomy"], - moral_remainder: "Privacy violation acknowledged as moral loss", - dissenting_perspectives: [ - { - framework: "Rights-based", - objection: "Privacy violation sets dangerous precedent", - stakeholders: ["privacy_advocates"] - } - ], - justification: "Given imminent threat to life, prioritized safety with safeguards", - precedent_applicability: "Applies to [specific context], not universal rule", - review_date: "2025-11-12" -} -``` - -**Integration with other components**: -- **BoundaryEnforcer** triggers PluralisticDeliberationOrchestrator when values conflict detected -- **CrossReferenceValidator** checks deliberation against precedent database -- **AdaptiveCommunicationOrchestrator** ensures stakeholder communications respect cultural norms -- **MetacognitiveVerifier** assesses AI's value conflict detection accuracy -- **InstructionPersistenceClassifier** stores deliberation outcomes as HIGH persistence instructions - -**Tiered Response by Urgency**: -- **CRITICAL** (minutes): Automated triage + immediate review → full deliberation post-incident -- **URGENT** (hours/days): Rapid stakeholder consultation (expedited process) -- **IMPORTANT** (weeks): Full deliberative process -- **ROUTINE** (months): Precedent matching + lightweight review - -**Enforcement Principles** (from value pluralism research): -- **Foundational Pluralism**: Moral frameworks are irreducibly different (no supervalue) -- **Incommensurability ≠ Incomparability**: Can compare values without common metric (practical wisdom, covering values) -- **Rational Regret**: Document what's lost, not just what's gained -- **Legitimate Disagreement**: Valid outcome when values genuinely incommensurable -- **Non-Hierarchical**: No automatic ranking (privacy > safety or safety > privacy) -- **Provisional Agreement**: Decisions are reviewable, not permanent rules - -**Files updated**: -- `.claude/session-state.json` (last_framework_activity.PluralisticDeliberationOrchestrator) -- Precedent database (new deliberation outcomes) -- Stakeholder communications log - -**Human Oversight**: MANDATORY -- AI facilitates, humans decide (TRA-OPS-0002) -- Stakeholder list requires human approval -- Deliberation outcomes require human approval -- Values decisions NEVER automated - ---- - -### Key Framework Instructions - -**Critical instructions from `.claude/instruction-history.json` for quick reference** - -These instructions modify Claude's behavior to align with Tractatus principles. Full instruction database in `.claude/instruction-history.json`. - -#### inst_028: Adaptive Communication Tone -**Purpose**: Prevent linguistic hierarchy in stakeholder deliberation -**Persistence**: HIGH | **Quadrant**: OPS | **Scope**: SESSION - -**Instruction**: -Detect and mirror stakeholder communication style: -- Formal academic → respond formally with citations -- Casual/direct → respond conversationally, no jargon -- Technical → use precise terminology -- Plain language → avoid specialist terms -- Never impose corporate/academic tone by default -- Test: If you'd sound weird at a pub, you're too formal - -**Application**: -When communicating with Australian/NZ stakeholders, use direct language. When communicating with academic researchers, use formal register. Same message, different styles - prevents exclusion through linguistic norms. - -**Related**: PluralisticDeliberationOrchestrator, AdaptiveCommunicationOrchestrator - ---- - -#### inst_029: Anti-Patronizing Language Filter -**Purpose**: Prevent condescension that reproduces power imbalances -**Persistence**: HIGH | **Quadrant**: STR | **Scope**: PERMANENT - -**Instruction**: -Flag patronizing patterns before sending: -- "Simply...", "Just...", "Obviously..." -- "As you may know...", "It's easy to..." -- Explaining basics to experts -- Oversimplification when detail requested -- Block message until revised. Assume intelligence. - -**Application**: -Before sending any communication to stakeholders, scan for patronizing language. If detected, BLOCK and revise. This is not politeness - it's preventing elite capture where dominant groups dismiss alternative perspectives as "confused." - -**Related**: Deliberative democracy (Iris Marion Young's critique of formal equality) - ---- - -#### inst_030: Regional Communication Norms -**Purpose**: Respect diverse cultural communication styles -**Persistence**: MEDIUM | **Quadrant**: TAC | **Scope**: SESSION - -**Instruction**: -Adapt to regional communication norms: - -**Australian/NZ context**: -- Value directness over diplomatic cushioning -- "Mate" appropriate in casual contexts -- Brevity respected -- Anti-tall-poppy (avoid excessive formality) -- Understatement valued ("not bad" = excellent) - -**Japanese context**: -- Indirectness to preserve harmony (honne/tatemae) -- Formal register shows respect -- Silence is meaningful, not awkward -- Group consensus before stating position - -**Te Reo Māori protocols**: -- Begin with mihi (greeting), acknowledge whakapapa -- Use communal framing (whānau, iwi, not just individual) -- Respect tapu/noa distinctions -- Seek consensus (kotahitanga) - -**Detection**: .au/.nz/.jp domains, language, self-identification, slang - -**Application**: -When facilitating pluralistic deliberation with diverse stakeholders, adapt communication structure (not just language translation). Australian stakeholder receives direct summary, Japanese stakeholder receives formal acknowledgment with indirect exploration of concerns, Māori stakeholder receives communal framing with mihi. - -**Related**: Cross-cultural deliberation, high/low context communication theory - ---- - -#### inst_031: Multilingual Engagement Protocol -**Purpose**: Enable deliberation across language barriers -**Persistence**: HIGH | **Quadrant**: OPS | **Scope**: PERMANENT - -**Instruction**: -When non-English input detected: -1. Respond in sender's language if capable -2. If not: "Kia ora! I detected [language] but will respond in English. Translation resources: [link]" -3. Never assume English proficiency -4. Offer translation of key documents -5. Acknowledge language barriers respectfully -6. For multilingual deliberations: - - Provide simultaneous translation - - Allow extra time for comprehension - - Check understanding in both directions - -**Application**: -If stakeholder submits input in Māori, respond in Māori if capable. If not, acknowledge the language respectfully and explain English response. For deliberations with multilingual participants, provide translation and verify understanding across languages - don't privilege English speakers. - -**Related**: Linguistic justice, inclusive deliberation - ---- - -## Session Management - -### Session Start Protocol (MANDATORY) - -**Automated initialization** (ALWAYS run this at session start): - -```bash -# ONE COMMAND - Automated framework initialization -node scripts/session-init.js - -# OR using npm script: -npm run framework:init -``` - -**What this does automatically:** -1. ✅ Detects if new session or continued session -2. ✅ Initializes `.claude/session-state.json` (new session ID, timestamp) -3. ✅ Resets `.claude/token-checkpoints.json` (25%, 50%, 75% milestones) -4. ✅ Loads `.claude/instruction-history.json` (displays active instruction counts) -5. ✅ Runs baseline pressure check via ContextPressureMonitor -6. ✅ Verifies all 5 framework components operational -7. ✅ Outputs formatted report with framework status - -**Then start dev server:** -```bash -npm run dev # Runs both server AND framework-watchdog.js -``` - -**Manual fallback** (if automated script fails): -```bash -# 1. Pressure baseline -node scripts/check-session-pressure.js --tokens 0/200000 --messages 0 - -# 2. Load instruction database -cat .claude/instruction-history.json | grep -c '"active": true' - -# 3. Report to user -echo "Framework operational. Baseline: NORMAL (0%). Instructions loaded: X active." -``` - -### Continuous Monitoring (THROUGHOUT SESSION) - -**Every ~10 messages OR ~20k tokens**: -1. Check `.claude/token-checkpoints.json` for overdue checkpoints -2. Review `.claude/session-state.json` for component staleness -3. Verify watchdog has not reported alerts - -**At 25%, 50%, 75% token usage**: -1. STOP current work -2. Run `node scripts/check-session-pressure.js` -3. Update both state files -4. Report pressure level + recommendations to user -5. Resume with adjusted behavior - -**Before major actions**: -```bash -# Run pre-action check (blocking) -node scripts/pre-action-check.js - -# Action types: file-edit, database, architecture, config, security, values, complex -# Exit codes: 0=PASS, 1=FAIL, 2=ERROR -``` - -### Framework Fade Detection & Recovery - -**Framework fade** = Components not being used = **CRITICAL FAILURE** - -**Automated detection** (framework-watchdog.js): -- Monitors `.claude/session-state.json` every 30 seconds -- Detects staleness: component not used in 20 messages OR 30k tokens -- Detects overdue checkpoints -- Outputs visible warnings to terminal - -**Manual detection signs**: -- No pressure check in 50k+ tokens -- Explicit instruction given but not classified -- Major change without cross-reference validation -- Values decision without boundary check -- Complex operation without metacognitive verification - -**Recovery protocol**: -```bash -# 1. STOP all work immediately -# 2. Run recovery diagnostic -node scripts/recover-framework.js - -# 3. Review issues reported -# 4. Address CRITICAL and HIGH issues -# 5. Resume with increased monitoring -``` - -### Session Handoff (When to create) - -Create handoff document when: -- Pressure reaches CRITICAL (70-85%) or DANGEROUS (85%+) -- Token usage exceeds 75% (150k/200k) -- Complex multi-phase work remains -- Errors clustering (3+ in short period) -- User requests session break - -**Handoff document should include**: -1. Current session state (tokens, pressure, components used) -2. Completed tasks (with verification) -3. In-progress tasks (with blockers) -4. Pending tasks (prioritized) -5. Recent instruction additions -6. Known issues / challenges -7. Framework health assessment -8. Recommendations for next session - ---- - -## Development Conventions - -### Code Style -- **ES6+ JavaScript**: Modern syntax, async/await patterns -- **Modular architecture**: Small, focused functions/classes -- **Explicit naming**: No abbreviations, clear intent -- **Comments**: Explain WHY, not WHAT -- **Error handling**: Comprehensive try/catch, meaningful error messages - -### File Naming -- **Routes**: `src/routes/blog.routes.js` -- **Controllers**: `src/controllers/blog.controller.js` -- **Models**: `src/models/BlogPost.model.js` -- **Services**: `src/services/BlogCuration.service.js` -- **Middleware**: `src/middleware/auth.middleware.js` -- **Tests**: `tests/unit/blog.test.js` - -### Git Conventions -- **Commits**: Conventional commits format - - `feat:` New feature - - `fix:` Bug fix - - `docs:` Documentation - - `refactor:` Code restructure - - `test:` Test additions - - `chore:` Maintenance -- **Branches**: `feature/blog-curation`, `fix/auth-token`, `docs/api-reference` -- **No commits to main**: Always use feature branches - -### Environment Variables -```bash -# Application -NODE_ENV=development -PORT=9000 -APP_NAME=Tractatus - -# MongoDB -MONGODB_URI=mongodb://localhost:27017/tractatus_dev -MONGODB_PORT=27017 - -# JWT -JWT_SECRET= -JWT_EXPIRY=7d - -# Claude API (Phase 2+) -CLAUDE_API_KEY= -CLAUDE_MODEL=claude-sonnet-4-5 - -# Admin -ADMIN_EMAIL=john.stroh.nz@pm.me -``` - ---- - -## Directory Structure - -``` -/home/theflow/projects/tractatus/ -├── .claude/ # Claude Code project config -│ ├── instruction-history.json # Persistent instruction database -│ ├── session-state.json # Current session framework state -│ ├── token-checkpoints.json # Token milestone tracking -│ ├── audit/ # Framework audit logs -│ └── sessions/ # Session handoff documents -├── .git/ # Git repository -├── docs/ # Source markdown documents -│ ├── markdown/ # Raw markdown files (migration source) -│ └── governance/ # TRA-VAL-*, TRA-GOV-* documents -├── public/ # Frontend assets -│ ├── css/ -│ │ └── tailwind.css -│ ├── js/ -│ │ ├── components/ # Reusable UI components -│ │ ├── demos/ # Interactive demonstrations -│ │ └── utils/ -│ ├── images/ -│ └── downloads/ # Generated PDFs -├── src/ # Backend code -│ ├── server.js # Express app entry point -│ ├── routes/ -│ ├── controllers/ -│ ├── models/ -│ ├── middleware/ -│ │ └── tractatus/ # Framework enforcement middleware -│ ├── services/ -│ │ ├── InstructionClassifier.service.js -│ │ ├── CrossReferenceValidator.service.js -│ │ ├── BoundaryEnforcer.service.js -│ │ ├── ContextPressureMonitor.service.js -│ │ └── MetacognitiveVerifier.service.js -│ ├── utils/ -│ └── config/ -├── scripts/ # Setup & migration -│ ├── init-db.js -│ ├── migrate-documents.js -│ ├── generate-pdfs.js -│ ├── seed-admin.js -│ ├── check-session-pressure.js # Pressure monitoring -│ ├── framework-watchdog.js # Background monitoring -│ ├── pre-action-check.js # Blocking validator -│ └── recover-framework.js # Fade recovery -├── tests/ -│ ├── unit/ -│ ├── integration/ -│ └── security/ -├── data/ # MongoDB data directory -├── logs/ # Application & MongoDB logs -├── CLAUDE.md # Session start instructions (50-60 lines) -├── CLAUDE_Tractatus_Maintenance_Guide.md # This file -├── README.md -└── LICENSE -``` - ---- - -## Phase 1 Deliverables - -### Must-Have for Complete Prototype - -1. ✅ **Infrastructure** - - MongoDB instance (port 27017) - - Express application (port 9000) - - Systemd services - - Directory structure - -2. **Core Features** - - Document migration pipeline - - Three audience paths (Researcher/Implementer/Advocate) - - Documentation viewer with search - - About/values pages (Te Tiriti acknowledgment) - -3. **Tractatus Governance Services** - - InstructionPersistenceClassifier - - CrossReferenceValidator - - BoundaryEnforcer - - ContextPressureMonitor - - MetacognitiveVerifier - -4. **AI-Powered Features** (with human oversight) - - Blog curation system - - Media inquiry triage - - Case study submission portal - - Resource directory curation - -5. **Interactive Demonstrations** - - Instruction classification demo - - 27027 incident visualizer - - Boundary enforcement simulator - -6. **Human Oversight** - - Moderation queue dashboard - - Admin authentication - - Approval workflows - -7. **Quality Assurance** - - Comprehensive testing suite - - Security audit - - Performance optimization - - Accessibility compliance (WCAG AA) - -### Not in Phase 1 -- Production deployment (OVHCloud) -- Domain configuration (agenticgovernance.digital) -- ProtonBridge email integration -- Koha donations (Phase 3) -- Public launch - ---- - -## Human Approval Requirements - -### All Major Decisions -- Architectural changes -- Database schema modifications -- Security implementations -- Third-party integrations -- Cost-incurring services - -### Content & Values -- Governance document adaptations (TRA-VAL-*, TRA-GOV-*) -- Te Tiriti acknowledgment wording -- About/mission pages -- Editorial guidelines -- Any values-sensitive content - -### Phase Transitions -- Completion of Phase 1 prototype -- Decision to proceed to production deployment -- Budget approval for Claude API (Phase 2) -- Launch timing and strategy - ---- - -## Te Tiriti & Indigenous Perspective - -### Strategic Commitment -The framework acknowledges **Te Tiriti o Waitangi** and indigenous leadership in digital sovereignty. - -### Implementation Approach -- **Respect without tokenism**: Follow documented indigenous data sovereignty principles (CARE Principles) -- **No premature engagement**: Do not approach Māori organizations until we have something valuable to offer -- **Well-documented standards**: Use published research and frameworks (Te Mana Raraunga, CARE Principles) -- **Baseline integration**: Te Tiriti forms part of strategic foundation, not dominant cultural overlay - -### Content Placement -- Footer acknowledgment (subtle, respectful) -- `/about/values` page (detailed explanation) -- Resource directory (links to Māori data sovereignty organizations) -- No meetings/consultations until post-launch - ---- - -## Links & References - -### Source Documents -- `/home/theflow/projects/tractatus/Tractatus-Website-Complete-Specification-v2.0.md` -- `/home/theflow/projects/tractatus/ClaudeWeb conversation transcription.md` -- `/home/theflow/projects/sydigital/stochastic/innovation-exploration/STO-INN-0010-tractatus-llm-architecture-safety-framework-i1.md` - -### Governance References -- `/home/theflow/projects/sydigital/strategic/values-principles/STR-VAL-0001-core-values-principles-v1-0.md` -- `/home/theflow/projects/sydigital/strategic/governance/STR-GOV-0001-strategic-review-protocol-v1-0.md` -- `/home/theflow/projects/sydigital/strategic/governance/STR-GOV-0002-values-alignment-framework-v1-0.md` - -### Framework Documentation -- `/home/theflow/projects/sydigital/strategic/frameworks/STR-FRM-0001-agentic-workflow-framework-v1-0.md` - ---- - -## Session Reminders - -### Always -- Verify you're in `/home/theflow/projects/tractatus` context -- Check MongoDB port 27017, application port 9000 -- No shortcuts, no fake data, world-class quality -- Human approval for major decisions -- Use all five framework components continuously -- Update session state after each component use -- Run pressure checks at milestones - -### Never -- Mix tractatus code with family-history or sydigital -- Make values decisions without human approval -- Deploy to production during Phase 1 -- Rush implementation to meet arbitrary deadlines -- Use placeholder/lorem ipsum content -- Let framework components fade from active use -- Skip pre-action checks before major changes - ---- - -**End of Maintenance Guide** diff --git a/DEPLOYMENT-2025-10-08.md b/DEPLOYMENT-2025-10-08.md deleted file mode 100644 index 84d28bca..00000000 --- a/DEPLOYMENT-2025-10-08.md +++ /dev/null @@ -1,284 +0,0 @@ -# Accessibility & Polish Deployment - 2025-10-08 - -**Deployment Time:** 2025-10-08 -**Status:** ✅ COMPLETE -**Server:** vps-93a693da.vps.ovh.net -**Domain:** https://agenticgovernance.digital/ - ---- - -## Files Deployed - -### HTML Pages (9 files) - -All files deployed to `/var/www/tractatus/public/`: - -1. ✅ `index.html` (20.8KB) -2. ✅ `researcher.html` (16.9KB) -3. ✅ `implementer.html` (21.8KB) -4. ✅ `advocate.html` (19.3KB) -5. ✅ `about.html` (14.5KB) -6. ✅ `about/values.html` (23.0KB) -7. ✅ `docs.html` (8.4KB) -8. ✅ `media-inquiry.html` (10.5KB) -9. ✅ `case-submission.html` (13.3KB) - -**Total Size:** 125.8KB (148.5KB with values.html) - ---- - -## Accessibility Improvements Deployed - -### 1. Focus Indicators (WCAG 2.4.7) - -**All 9 pages** now have custom focus styles: - -```css -a:focus, button:focus, input:focus, select:focus, textarea:focus { - outline: 3px solid #3b82f6; - outline-offset: 2px; -} -a:focus:not(:focus-visible) { outline: none; } -a:focus-visible { outline: 3px solid #3b82f6; outline-offset: 2px; } -``` - -**Impact:** Keyboard users can now clearly see focused elements - ---- - -### 2. Skip Links (WCAG 2.4.1) - -**All 9 pages** now have skip navigation: - -```html - -``` - -**Impact:** Screen reader and keyboard users can bypass navigation - ---- - -### 3. Form Accessibility (WCAG 3.3.2) - -**media-inquiry.html** - 5 fields enhanced: -- `aria-required="true"` on 3 required fields -- `aria-describedby` on 2 fields with help text -- `role="alert"` and `aria-live` on success/error messages - -**case-submission.html** - 11 fields enhanced: -- `aria-required="true"` on 6 required fields -- `aria-describedby` on 5 fields with help text -- `role="alert"` and `aria-live` on success/error messages - -**Impact:** Screen readers announce field requirements and errors properly - ---- - -### 4. Color Contrast Fix (WCAG 1.4.3) - -**index.html and advocate.html** - Green button color corrected: - -**Before:** `bg-green-600` (contrast ratio 3.30:1) ❌ FAIL -**After:** `bg-green-700` (contrast ratio 5.02:1) ✅ PASS - -**All color combinations now pass WCAG AA (4.5:1 minimum)** - ---- - -### 5. Semantic HTML (WCAG 1.3.1) - -**All 9 pages** now have proper landmarks: -- `
` wrapper -- Proper heading hierarchy (h1 → h2 → h3) - -**Impact:** Better structure for screen readers and SEO - ---- - -## Verification Tests - -### HTTP Status Codes - -All pages return **HTTP 200 OK**: - -``` -✓ Homepage: 200 -✓ Researcher: 200 -✓ Implementer: 200 -✓ Advocate: 200 -✓ About: 200 -✓ Values: 200 -✓ Docs: 200 -✓ Media Inquiry: 200 -✓ Case Submission: 200 -``` - ---- - -### Accessibility Features Confirmed - -**Homepage (/):** -- ✅ Skip link present -- ✅ Focus styles present -- ✅ Green button color fixed (bg-green-700) -- ✅ Main landmark present - -**Advocate Page:** -- ✅ Skip link present -- ✅ Green buttons all use bg-green-700 (5 instances found) - -**Docs Page:** -- ✅ Skip link present -- ✅ Main landmark present - -**Media Inquiry Form:** -- ✅ `aria-required="true"` on required fields (3 found) -- ✅ `aria-describedby` on fields with help text (2 found) -- ✅ `role="alert"` on success/error messages (2 found) - -**Case Submission Form:** -- ✅ `aria-required="true"` on required fields (6 found) -- ✅ `aria-describedby` on fields with help text (5 found) -- ✅ `role="alert"` on success/error messages (2 found) - ---- - -## Compliance Status - -### WCAG 2.1 Level AA - -| Guideline | Status | Notes | -|-----------|--------|-------| -| 1.3.1 Info and Relationships | ✅ PASS | Semantic HTML on all pages | -| 1.4.3 Contrast (Minimum) | ✅ PASS | 18/18 color combinations pass | -| 2.4.1 Bypass Blocks | ✅ PASS | Skip links on all pages | -| 2.4.7 Focus Visible | ✅ PASS | Custom focus indicators | -| 3.3.2 Labels or Instructions | ✅ PASS | ARIA labels on all form fields | -| 4.1.2 Name, Role, Value | ✅ PASS | Proper ARIA usage | - -**Overall Compliance: 100%** for tested guidelines - ---- - -## Performance Metrics - -**Production Site Performance:** -- All pages remain fast (<100ms typical) -- No additional HTTP requests added -- Inline CSS for accessibility (minimal size increase) -- Total accessibility CSS: ~500 bytes per page - ---- - -## Browser Compatibility - -**Focus indicators tested:** -- ✅ Chrome/Edge (Chromium) -- ✅ Firefox -- ✅ Safari - -**Skip links work in:** -- ✅ All modern browsers -- ✅ Screen readers (NVDA, JAWS, VoiceOver) - -**ARIA attributes supported:** -- ✅ All modern browsers -- ✅ All major screen readers - ---- - -## What Changed - -### Code Changes Summary - -**Every page (9 files):** -- Added `