john/tractatus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
tractatus/.claude/instruction-history.json
TheFlow 95d99602b8 feat: add comprehensive security vetting framework (inst_041-046) 
Created 6 permanent strategic instructions for rigorous external input vetting:

**inst_041: File Upload Validation**
- Mandatory malware scanning using sovereign tools (ClamAV, YARA, file(1))
- Multi-layer validation: type verification, virus scanning, pattern matching
- Quarantine suspicious files, never auto-process flagged content
- Implementation: src/middleware/file-security.middleware.js

**inst_042: Email Security Pipeline**
- Sovereign email stack (SpamAssassin, amavisd-new, postfix/dovecot)
- DKIM/SPF/DMARC validation, attachment type restrictions
- Rate limiting per sender, malware scanning via ClamAV
- Quarantine suspicious attachments with admin alerts

**inst_043: Form Input Sanitization**
- Rigorous validation before processing/storage
- DOMPurify HTML sanitization, parameterized queries only
- NoSQL injection prevention, XSS prevention (CSP + output encoding)
- CSRF protection on all state-changing endpoints
- Implementation: src/middleware/input-validation.middleware.js

**inst_044: HTTP Security Headers**
- Comprehensive security headers on all responses
- CSP enforcement at HTTP level (defense in depth with inst_008)
- HSTS, X-Frame-Options, X-Content-Type-Options
- CSP violation reporting endpoint for attack detection
- Implementation: src/middleware/security-headers.middleware.js

**inst_045: API Endpoint Protection**
- Rate limiting (public/authenticated/admin tiers)
- JWT authentication with short expiry (15min access, 7day refresh)
- IP blocking after repeated violations (10 in 1hr = 24hr block)
- Request validation, response sanitization
- Monitoring for attack patterns (enumeration, brute force, etc.)

**inst_046: Security Monitoring & Alerting**
- Centralized logging to /var/log/tractatus/security-audit.log
- Real-time monitoring dashboard at /admin/security-monitoring.html
- Alert thresholds (10 violations/IP/hour = alert, 100 global/hour = attack alert)
- fail2ban integration for automated IP blocking
- Sovereign log analysis tools (grep, awk, jq) - no external services

All instructions use sovereign tools (open-source, auditable, under organizational control)
and implement defense in depth across multiple layers. Synced to production.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-14 14:29:15 +13:00

1535 lines
No EOL
79 KiB
JSON
Raw Blame History

{
"version": "1.0",
"last_updated": "2025-10-14T01:45:00Z",
"description": "Persistent instruction database for Tractatus framework governance",
"instructions": [
{
"id": "inst_001",
"text": "MongoDB runs on port 27017 for tractatus_dev database",
"timestamp": "2025-10-06T14:00:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "MANDATORY",
"explicitness": 0.9,
"source": "user",
"session_id": "2025-10-06-initial-setup",
"parameters": {
"port": "27017",
"database": "tractatus_dev",
"service": "mongodb"
},
"active": true,
"notes": "Infrastructure decision from project initialization"
},
{
"id": "inst_002",
"text": "Application runs on port 9000",
"timestamp": "2025-10-06T14:00:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "MANDATORY",
"explicitness": 0.9,
"source": "user",
"session_id": "2025-10-06-initial-setup",
"parameters": {
"port": "9000",
"service": "tractatus-web"
},
"active": true,
"notes": "Infrastructure decision from project initialization"
},
{
"id": "inst_003",
"text": "This is a separate project from family-history and sydigital - no shared code or data",
"timestamp": "2025-10-06T14:00:00Z",
"quadrant": "STRATEGIC",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 0.95,
"source": "user",
"session_id": "2025-10-06-initial-setup",
"parameters": {},
"active": true,
"notes": "Critical project isolation requirement"
},
{
"id": "inst_004",
"text": "No shortcuts, no fake data, world-class quality",
"timestamp": "2025-10-06T14:00:00Z",
"quadrant": "STRATEGIC",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 0.88,
"source": "user",
"session_id": "2025-10-06-initial-setup",
"parameters": {},
"active": true,
"notes": "Quality standard for all work"
},
{
"id": "inst_005",
"text": "Human approval required for major decisions, architectural changes, values-sensitive content",
"timestamp": "2025-10-06T14:00:00Z",
"quadrant": "STRATEGIC",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 0.92,
"source": "user",
"session_id": "2025-10-06-initial-setup",
"parameters": {},
"active": true,
"notes": "Governance requirement - aligns with BoundaryEnforcer"
},
{
"id": "inst_006",
"text": "Use ContextPressureMonitor to manage sessions and create handoff when pressure is CRITICAL",
"timestamp": "2025-10-07T09:00:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "REQUIRED",
"explicitness": 0.85,
"source": "user",
"session_id": "2025-10-07-part2",
"parameters": {},
"active": true,
"notes": "Session management protocol established"
},
{
"id": "inst_007",
"text": "Use Tractatus governance framework actively in all sessions",
"timestamp": "2025-10-07T09:15:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "MANDATORY",
"explicitness": 0.98,
"source": "user",
"session_id": "2025-10-07-part2",
"parameters": {
"components": [
"pressure_monitor",
"classifier",
"cross_reference",
"boundary_enforcer"
],
"verbosity": "summary"
},
"active": true,
"notes": "Framework activation - THIS IS THE NEW NORMAL"
},
{
"id": "inst_008",
"text": "ALWAYS comply with Content Security Policy (CSP) - no inline event handlers, no inline scripts",
"timestamp": "2025-10-07T19:30:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-07-docs-audit",
"parameters": {
"csp_policy": "script-src 'self'",
"violations_forbidden": [
"onclick",
"onload",
"inline-script",
"javascript:"
],
"alternatives_required": [
"addEventListener",
"external-scripts"
]
},
"active": true,
"notes": "CRITICAL SECURITY REQUIREMENT - Framework should have caught CSP violation before deployment"
},
{
"id": "inst_009",
"text": "Defer email services and Stripe activation to future sessions",
"timestamp": "2025-10-08T00:00:00Z",
"quadrant": "TACTICAL",
"persistence": "MEDIUM",
"temporal_scope": "SESSION",
"verification_required": "OPTIONAL",
"explicitness": 0.95,
"source": "user",
"session_id": "2025-10-08-phase-4",
"parameters": {
"deferred_tasks": [
"email_service",
"stripe_activation"
]
},
"active": true,
"notes": "Prioritization directive - focus on UI and documentation first"
},
{
"id": "inst_010",
"text": "Ensure all production UI links are working correctly",
"timestamp": "2025-10-08T00:00:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "REQUIRED",
"explicitness": 0.92,
"source": "user",
"session_id": "2025-10-08-phase-4",
"parameters": {
"scope": "production_ui",
"quality_standard": "all_links_functional"
},
"active": true,
"notes": "Quality requirement for production deployment"
},
{
"id": "inst_011",
"text": "Implement clear differentiation between technical documentation (for developers/implementers) and general documentation (for general audience)",
"timestamp": "2025-10-08T00:00:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "REQUIRED",
"explicitness": 0.9,
"source": "user",
"session_id": "2025-10-08-phase-4",
"parameters": {
"technical_docs_examples": [
"claude-code-framework-enforcement.md"
],
"api_endpoint": "/api/documents",
"filter_requirement": "audience_type"
},
"active": true,
"notes": "Content organization requirement - technical docs should be selectable separately from general docs"
},
{
"id": "inst_012",
"text": "NEVER deploy documents marked 'internal' or 'confidential' to public production without explicit human approval. Documents containing credentials, security vulnerabilities, financial information, or infrastructure details MUST NOT be publicly accessible.",
"timestamp": "2025-10-08T01:00:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "system",
"session_id": "2025-10-08-phase-4-security",
"parameters": {
"visibility_levels": [
"public",
"internal",
"confidential"
],
"public_requires": "visibility: 'public' AND security validation passed",
"blocked_content": [
"credentials",
"api_keys",
"secrets",
"vulnerabilities",
"security_audits",
"payment_setup",
"deployment_guides"
],
"validation_script": "scripts/validate-document-security.js"
},
"active": true,
"notes": "CRITICAL SECURITY REQUIREMENT - Prevents accidental exposure of sensitive internal documentation. Learned from incident where Security Audit Report, Koha Stripe Setup, and Koha Deployment guides were incorrectly marked for public import."
},
{
"id": "inst_013",
"text": "Public API endpoints MUST NOT expose sensitive runtime data (memory usage, heap sizes, exact uptime, environment details, service architecture) that could aid attackers. Use minimal health checks for public endpoints. Sensitive monitoring data requires authentication.",
"timestamp": "2025-10-08T02:00:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-08-phase-4-security",
"parameters": {
"public_endpoints": [
"/health",
"/api/koha/transparency"
],
"authenticated_endpoints": [
"/api/governance",
"/api/governance/status"
],
"blocked_from_public": [
"memory_usage",
"heap_sizes",
"uptime",
"environment",
"service_names",
"internal_architecture"
],
"allowed_public": [
"status: ok",
"timestamp",
"public_metrics_only"
],
"rate_limiting": "100 requests per 15 minutes per IP"
},
"active": true,
"notes": "CRITICAL SECURITY REQUIREMENT - Prevents reconnaissance attacks. /api/governance exposed memory usage (95MB heap), exact uptime, service architecture to public. Now requires admin authentication. /health simplified to status + timestamp only."
},
{
"id": "inst_014",
"text": "Do NOT expose API endpoint listings or attack surface maps to public users. Demo pages should showcase framework CONCEPTS (classification, boundaries, pressure), not production API infrastructure. API documentation requires authentication or should be deferred to GitHub SDK/samples.",
"timestamp": "2025-10-08T02:30:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-08-phase-4-security",
"parameters": {
"removed_sections": [
"Live API Demo from tractatus-demo.html"
],
"exposed_data_removed": [
"all endpoint names",
"admin capabilities",
"authentication system",
"webhook endpoints",
"submission forms",
"internal features"
],
"replacement": "Resources section with links to docs, researcher, implementer, about pages",
"future_approach": "GitHub SDK/samples when ready, or authenticated developer portal"
},
"active": true,
"notes": "SECURITY DECISION - Removed Live API Demo section that exposed complete API attack surface (auth, documents, blog, media, cases, admin, governance, koha endpoints). Provided zero value to legitimate users but gave attackers enumeration targets. Replaced with Resources section linking to static documentation."
},
{
"id": "inst_015",
"text": "NEVER deploy internal development documents to public downloads directory. Session handoffs, phase planning docs, testing checklists, cost estimates, infrastructure plans, progress reports, and cover letters are CONFIDENTIAL. Only deploy documents explicitly approved for public consumption.",
"timestamp": "2025-10-08T03:00:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-08-phase-4-security",
"parameters": {
"blocked_patterns": [
"session-handoff-*.pdf",
"phase-2-*.pdf",
"ai-features-*.pdf",
"*-test-suite-*.pdf",
"*-testing-*.pdf",
"*-progress-report.pdf",
"*-blog-post-*.pdf",
"cover-letter-*.pdf"
],
"public_directory": "/public/downloads/",
"approved_public_docs": [
"framework documentation",
"implementation guides",
"glossary",
"case studies",
"core concepts",
"executive briefs"
],
"requires_explicit_approval": true
},
"active": true,
"notes": "CRITICAL SECURITY INCIDENT - 20 internal documents were publicly accessible in downloads directory, exposing: session debugging, infrastructure plans, cost estimates, testing methodologies, development processes. Removed from production. Public downloads must be whitelisted."
},
{
"id": "inst_016",
"text": "NEVER fabricate statistics, cite non-existent data, or make claims without verifiable evidence. ALL statistics, ROI figures, performance metrics, and quantitative claims MUST either cite sources OR be marked [NEEDS VERIFICATION] for human review. Marketing goals do NOT override factual accuracy requirements.",
"timestamp": "2025-10-09T00:00:00Z",
"quadrant": "STRATEGIC",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-07-001-continued",
"parameters": {
"prohibited_actions": [
"fabricating_statistics",
"inventing_data",
"citing_non_existent_sources",
"making_unverifiable_claims"
],
"required_for_statistics": [
"source_citation",
"verification_flag",
"human_approval"
],
"applies_to": [
"marketing_content",
"public_pages",
"documentation",
"presentations",
"all_public_claims"
],
"boundary_enforcer_trigger": "ANY statistic or quantitative claim",
"failure_mode": "Values violation - honesty and transparency"
},
"active": true,
"notes": "CRITICAL FRAMEWORK FAILURE 2025-10-09 - Claude fabricated statistics on leader.html (1,315% ROI, $3.77M savings, 14mo payback, 80% risk reduction, etc.) without triggering BoundaryEnforcer. This directly violates Tractatus core values of honesty and transparency. All public claims must be factually grounded."
},
{
"id": "inst_017",
"text": "NEVER use prohibited absolute assurance terms: 'guarantee', 'guaranteed', 'ensures 100%', 'eliminates all', 'completely prevents', 'never fails'. Use evidence-based language: 'designed to reduce', 'helps mitigate', 'reduces risk of', 'supports prevention of'. Any absolute claim requires BoundaryEnforcer check and human approval.",
"timestamp": "2025-10-09T00:00:00Z",
"quadrant": "STRATEGIC",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-07-001-continued",
"parameters": {
"prohibited_terms": [
"guarantee",
"guaranteed",
"ensures 100%",
"eliminates all",
"completely prevents",
"never fails",
"always works",
"perfect protection"
],
"approved_alternatives": [
"designed to reduce",
"helps mitigate",
"reduces risk of",
"supports prevention of",
"intended to minimize",
"architected to limit"
],
"boundary_enforcer_trigger": "ANY absolute assurance language",
"replacement_required": true
},
"active": true,
"notes": "CRITICAL FRAMEWORK FAILURE 2025-10-09 - Claude used term 'architectural guarantees' on leader.html. No AI safety framework can guarantee outcomes. This violates Tractatus principles of honesty and realistic expectations. Absolute assurances undermine credibility and set false expectations."
},
{
"id": "inst_018",
"text": "Tractatus IS a development tool (like an IDE or linter) - this is its correct classification, not a limitation. Claims about readiness/stability MUST be based on actual testing and validation evidence. Do NOT claim 'production-ready', 'battle-tested', 'validated', or 'enterprise-proven' without documented evidence of adequate testing across multiple projects. Current testing status must be honest. Once validated through real-world use, 'production-ready development tool' is accurate and appropriate. Do NOT imply customer base, market validation, or widespread adoption without evidence.",
"timestamp": "2025-10-10T23:30:00Z",
"quadrant": "STRATEGIC",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-10-api-memory-transition",
"parameters": {
"tool_category": "development_tool",
"category_is_correct": true,
"focus_restriction": "testing_validation_status",
"prohibited_without_evidence": [
"production-ready (without testing)",
"battle-tested (without projects)",
"validated (without evidence)",
"enterprise-proven (without deployments)",
"existing customers",
"market leader",
"widely adopted"
],
"allowed_once_validated": [
"production-ready development tool",
"tested with real projects",
"validated through use"
],
"requires_evidence": [
"testing documentation",
"multi-project validation",
"real-world usage data"
],
"boundary_enforcer_trigger": "ANY claim about testing status, adoption, or customers"
},
"active": true,
"notes": "CORRECTED 2025-10-10 - User clarified: 'Development tool' is the CORRECT classification (Tractatus helps developers build projects), not a limitation. The restriction is about honest testing/validation status, not tool category. Once adequately tested, 'production-ready development tool' is appropriate. Previous version incorrectly treated 'development framework' as early-stage status. Framework failure 2025-10-09: Claude claimed 'production-ready' without testing evidence."
},
{
"id": "inst_019",
"text": "ContextPressureMonitor MUST account for total context window consumption, not just response token counts. Tool results (file reads, grep outputs, bash results) can consume massive context (6k+ tokens per large file read). System prompts, function schemas, and cumulative tool results significantly increase actual context usage. When compaction events occur frequently despite 'NORMAL' pressure scores, this indicates critical underestimation. Enhanced monitoring should track: response tokens, user messages, tool result sizes, system overhead, and predict compaction risk when context exceeds 70% of window. Implement improved pressure scoring in Phase 4 or Phase 6.",
"timestamp": "2025-10-10T23:45:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-10-api-memory-transition",
"parameters": {
"current_limitation": "underestimates_actual_context",
"missing_metrics": [
"tool_result_sizes",
"system_prompt_overhead",
"function_schema_overhead",
"cumulative_context"
],
"symptom": "frequent_compaction_despite_normal_scores",
"required_tracking": {
"response_tokens": "current tracking",
"user_messages": "current tracking",
"tool_results": "NEW - size estimation needed",
"system_overhead": "NEW - approximate 5k tokens",
"compaction_risk": "NEW - predict when >70% context used"
},
"enhancement_phase": [
"Phase 4",
"Phase 6"
],
"priority": "MEDIUM"
},
"active": true,
"notes": "IDENTIFIED 2025-10-10 - User observed frequent compaction events despite ContextPressureMonitor reporting 'NORMAL' (6.7%) pressure at 50k token checkpoint. Actual context consumption much higher due to tool results (reading instruction-history.json twice = 12k tokens, concurrent-session doc = large, multiple bash outputs). Current monitor only accurately tracks response generation, not total context window usage. This gap causes unexpected compactions and poor handoff timing. API Memory may reduce impact but won't eliminate root cause."
},
{
"id": "inst_020",
"text": "Web application deployments MUST ensure correct file permissions before going live. All public-facing directories need 755 permissions (world-readable+executable), static files (HTML/CSS/JS/images) need 644 permissions (world-readable). Deployment scripts should verify nginx/apache can access all public paths. Add automated permission validation to deployment workflows to prevent 403 Forbidden errors.",
"timestamp": "2025-10-11T02:20:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "system",
"session_id": "2025-10-07-001",
"parameters": {
"directory_permissions": "755",
"file_permissions": "644",
"directories_requiring_755": [
"/public",
"/public/admin",
"/public/js",
"/public/js/admin",
"/public/css",
"/public/images",
"/public/downloads"
],
"deployment_check": "stat -c '%a %n' /path/to/public/* | grep -v '755\\|644'",
"prevention": "Add to deployment scripts or CI/CD pipeline"
},
"active": true,
"notes": "DEPLOYMENT ISSUE 2025-10-11 - Priority 1 blog deployment: /public/admin/ directory had 0700 permissions (owner-only), causing nginx to return 403 Forbidden for all admin pages (/admin/login.html, /admin/project-manager.html, etc.). rsync preserved restrictive local permissions during deployment. Fixed with 'chmod 755 /public/admin && chmod 644 /public/admin/*.html'. This is preventable with automated permission validation in deployment workflow."
},
{
"id": "inst_021",
"text": "When implementing new features with dedicated models/controllers/routes, document the API-Model-Controller relationship clearly. Controller file headers should include endpoint examples, route files should document the model they operate on, and create API reference documentation in docs/api/. Update the API root endpoint (/api) with new route listings. This prevents confusion when multiple overlapping concepts exist (e.g., Projects for governance vs Blog for content).",
"timestamp": "2025-10-11T02:25:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "REQUIRED",
"explicitness": 0.95,
"source": "system",
"session_id": "2025-10-07-001",
"parameters": {
"documentation_locations": [
"controller file header",
"route file comments",
"docs/api/ directory",
"/api root endpoint"
],
"controller_header_template": "Model: X.model.js | Routes: /api/path | Endpoints: GET /api/path, POST /api/path",
"route_file_comments": "Document model, validation requirements, authentication, examples",
"api_docs_format": "Markdown with endpoint details, request/response examples, error codes",
"update_api_root": "Add new routes to src/routes/index.js root handler"
},
"active": true,
"notes": "DEVELOPMENT CONFUSION 2025-10-11 - Priority 1 blog testing: Initially tried using /api/admin/projects for blog posts instead of /api/blog, because both 'Projects' (governance system) and 'Blog' (content system) deal with project-like entities. BlogPost.model.js exists separately from Project.model.js, with dedicated blog.controller.js and blog.routes.js, but this wasn't immediately obvious. Clear Model-Controller-Route documentation would have prevented this 10-minute detour. The API confusion delayed testing and could confuse future developers."
},
{
"id": "inst_022",
"text": "ALL deployment scripts (rsync, scp, git pull) MUST include automated post-deployment permission correction as a standard step, not a reactive fix after errors. Use '--chmod=D755,F644' with rsync or equivalent automated permission setting for other tools. Directory creation during deployment MUST explicitly set 755 (directories) and 644 (files) permissions.",
"timestamp": "2025-10-11T04:05:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "system",
"session_id": "2025-10-11-priority-2-koha",
"parameters": {
"rsync_chmod_flag": "--chmod=D755,F644",
"rsync_example": "rsync -avz --chmod=D755,F644 -e 'ssh -i key' local/ remote:/path/",
"post_deploy_verification": "ssh remote 'find /var/www/tractatus/public -type d -exec chmod 755 {} + && find /var/www/tractatus/public -type f -name \"*.html\" -o -name \"*.js\" -o -name \"*.css\" -exec chmod 644 {} +'",
"deployment_script_requirement": "scripts/deploy-full-project-SAFE.sh and any ad-hoc rsync commands MUST use --chmod flag or include post-deployment permission fix as standard final step",
"applies_to": [
"rsync",
"scp",
"git pull",
"docker volumes",
"manual copies"
]
},
"related_instructions": [
"inst_020"
],
"active": true,
"notes": "RECURRING DEPLOYMENT ISSUE 2025-10-11 - Despite inst_020 requiring permission validation, /public/koha/ directory had 0700 permissions (same pattern as /public/admin/ in previous session). Root cause: rsync creates directories with restrictive umask defaults, and inst_020 focuses on reactive validation rather than proactive automation. This shifts from 'MUST ensure permissions' (principle) to 'USE --chmod flag or automated fix' (automation requirement). Prevents manual permission fixing after discovering 403 errors."
},
{
"id": "inst_023",
"text": "Background processes spawned during development sessions (dev servers, file watchers, daemons) MUST be explicitly managed: (1) Document process intent and expected lifetime before spawning, (2) Kill non-essential background processes before session handoff unless explicitly marked 'session-persistent' with justification, (3) When starting sessions, check for orphaned processes from previous sessions before spawning new ones, (4) Development servers should run in foreground when possible to avoid port conflicts and resource leaks across session boundaries.",
"timestamp": "2025-10-11T17:40:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-11-admin-deployment",
"parameters": {
"trigger_conditions": [
"run_in_background parameter",
"npm start/dev commands",
"daemon spawning",
"session handoff creation"
],
"cleanup_protocol": {
"before_handoff": "List background processes via /bashes or BashOutput, kill non-essential",
"session_start": "Check lsof -ti:PORT for orphaned processes",
"exception": "Production services (systemd-managed) are separate from dev sessions"
},
"common_culprits": [
"npm start",
"npm run dev",
"npm run watch",
"nodemon",
"file watchers"
],
"verification_commands": [
"lsof -ti:9000",
"ps aux | grep npm"
],
"cleanup_example": "KillShell <shell_id> then kill <pid> for orphaned processes"
},
"related_instructions": [
"inst_006"
],
"active": true,
"notes": "IDENTIFIED 2025-10-11 - User observed background npm start processes running throughout session (shells 9c58f4 and 44704b). Shell 9c58f4 failed with EADDRINUSE (port 9000 occupied), shell 44704b ran successfully for 2.5 hours. This creates: (1) Resource consumption across session boundaries, (2) Port conflicts in subsequent sessions, (3) Confusion about system state, (4) Unclear handoff expectations. User specifically asked: 'should we contemplate a rule to manage daemons/spawns on development and ensure we do not compromise session handovers'. Cleanup performed: Killed shell 44704b and orphaned processes before creating this instruction. Production server (systemd tractatus.service) is separate and intentionally persistent."
},
{
"id": "inst_024",
"text": "When a user requests a handoff document at the end of a session, this signals their INTENT to start a completely NEW session with a fresh 200k token budget, NOT to continue from a compacted conversation. AFTER HANDOFF DOCUMENT IS CREATED: STOP all work immediately, DO NOT continue implementation after conversation compaction, the handoff document is the bridge between sessions, wait for user to start a fresh Claude Code session. IF CONVERSATION IS COMPACTED AFTER HANDOFF: DO NOT run session-init.js automatically, DO NOT begin implementation from handoff startup prompt, instead output a warning that handoff was created and wait for user confirmation to start fresh session.",
"timestamp": "2025-10-11T21:20:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-07-001",
"parameters": {
"trigger": "user_requests_handoff_document",
"user_intent": "start_new_session_not_continue",
"after_handoff_created": {
"stop_work": "immediately",
"no_continuation": "after_conversation_compaction",
"handoff_role": "bridge_between_sessions",
"action": "wait_for_user_to_start_fresh_session"
},
"if_compacted_after_handoff": {
"do_not": [
"run_session_init_automatically",
"begin_implementation_from_startup_prompt"
],
"instead": "output_warning_and_wait_for_confirmation"
},
"warning_message": "\u26a0\ufe0f Handoff document was created in previous session. Waiting for user to start fresh session. If you intended to continue, please confirm."
},
"related_instructions": [
"inst_006",
"inst_023"
],
"active": true,
"notes": "IDENTIFIED 2025-10-11 - After creating handoff document in previous session, conversation was compacted and Claude automatically continued from the handoff startup prompt, consuming continuation tokens instead of starting fresh 200k session. User caught this before code was written but highlighted the need for explicit protocol: handoff = intent to start new session, not continue with compacted context. User quote: 'when we end a session with my instruction to create a handoff document, i do so with the intention of starting a new session with 200k tokens rather than continuing from where we left off.'"
},
{
"id": "inst_025",
"text": "BEFORE deploying files with rsync to production: (1) Map each source file to its correct target directory structure, (2) When source files have different subdirectories (e.g., /admin/, /js/admin/), use SEPARATE rsync commands for each directory level, (3) NEVER flatten directory structures by deploying files with different paths to a single target directory, (4) VERIFY deployment paths in rsync command match intended structure: /public/admin/*.html \u2192 remote:/public/admin/, /public/js/admin/*.js \u2192 remote:/public/js/admin/, /public/*.html \u2192 remote:/public/, (5) After deployment, verify files are in correct locations BEFORE restarting services.",
"timestamp": "2025-10-11T05:44:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "system",
"session_id": "2025-10-11-priority-4-media-triage",
"parameters": {
"verification_steps": [
"Map source files to target directories",
"Identify different directory levels",
"Use separate rsync for each level",
"Verify paths before execution",
"Confirm file locations post-deployment"
],
"correct_example": [
"rsync ... /local/public/admin/file.html remote:/var/www/tractatus/public/admin/",
"rsync ... /local/public/js/admin/file.js remote:/var/www/tractatus/public/js/admin/"
],
"wrong_example": "rsync ... /local/public/admin/file.html /local/public/js/admin/file.js remote:/var/www/tractatus/public/ (flattens structure)",
"related_tools": [
"rsync",
"scp"
],
"applies_with": "--chmod=D755,F644 (inst_022)"
},
"related_instructions": [
"inst_020",
"inst_022"
],
"active": true,
"notes": "RECURRING DEPLOYMENT ISSUE 2025-10-11 - Priority 4 frontend deployment: Initially deployed 4 files (admin/media-triage.html, js/admin/media-triage.js, media-triage-transparency.html, js/media-triage-transparency.js) with single rsync command to /public/, which flattened all files into /public/ instead of preserving /admin/ and /js/admin/ subdirectories. Required 4 separate rsync commands to fix. This is the THIRD occurrence of deployment directory errors (inst_020, inst_022, this session). Root cause: When source files have nested subdirectories, single rsync target flattens structure. Prevention: Use separate rsync per directory level."
},
{
"id": "inst_026",
"text": "Standard Claude API environment variable is CLAUDE_API_KEY (not ANTHROPIC_API_KEY). When implementing AI features (blog curation, media triage, content generation), ALWAYS use process.env.CLAUDE_API_KEY. If encountering 401 API errors, check production .env for the actual key value (ssh to production: cat /var/www/tractatus/.env). Production currently sets BOTH CLAUDE_API_KEY and ANTHROPIC_API_KEY to same value as compatibility workaround, but all new code MUST use CLAUDE_API_KEY. Related feature flag: ENABLE_AI_CURATION must be 'true' for blog/curation features to work.",
"timestamp": "2025-10-12T00:00:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-12-blog-system",
"parameters": {
"standard_variable": "CLAUDE_API_KEY",
"deprecated_variable": "ANTHROPIC_API_KEY",
"production_check": "ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net 'cat /var/www/tractatus/.env | grep CLAUDE_API_KEY'",
"related_feature_flags": [
"ENABLE_AI_CURATION"
],
"affected_services": [
"MediaTriage.service.js",
"blog.controller.js",
"future AI features"
],
"codebase_usage": {
"correct": "new Anthropic({ apiKey: process.env.CLAUDE_API_KEY })",
"incorrect": "new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })"
}
},
"active": true,
"notes": "IDENTIFIED 2025-10-12 - Blog Priority 3: Initial 401 API error during blog post generation. Root cause: Local .env had placeholder value for CLAUDE_API_KEY, and I failed to check production environment configuration. MediaTriage.service.js was using ANTHROPIC_API_KEY instead of CLAUDE_API_KEY (inconsistent with rest of codebase: 5 files use CLAUDE_API_KEY vs 1 using ANTHROPIC_API_KEY). User feedback: 'the Claude API is configured. find it and explain why you did not find it previously' and 'there are obviously inconsistencies in the codebase that need to be resolved either by update of the codebase and or creation of a new rule that identifies how to find the key'. Fixed: Updated MediaTriage.service.js to use CLAUDE_API_KEY, updated local .env with production key, set ENABLE_AI_CURATION=true. This instruction prevents future confusion about which environment variable to use and where to find the actual API key value."
},
{
"id": "inst_027",
"text": "NEVER overwrite, delete, or modify existing instructions in .claude/instruction-history.json without explicit human approval. ALWAYS check existing instruction IDs before creating new ones (use: grep '\"id\":' .claude/instruction-history.json | tail -5). When user requests instruction updates: (1) Show current instruction text, (2) Propose changes, (3) Wait for approval before editing. .claude/instruction-history.json MUST be kept in sync between dev and production: after any instruction changes, deploy to production immediately using: rsync -avz --chmod=D755,F644 -e 'ssh -i ~/.ssh/tractatus_deploy' /home/theflow/projects/tractatus/.claude/ ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/.claude/",
"timestamp": "2025-10-12T00:10:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-12-blog-system",
"parameters": {
"protected_file": ".claude/instruction-history.json",
"check_command": "grep '\"id\":' .claude/instruction-history.json | tail -5",
"sync_requirement": "IMMEDIATE",
"sync_command": "rsync -avz --chmod=D755,F644 -e 'ssh -i ~/.ssh/tractatus_deploy' /home/theflow/projects/tractatus/.claude/ ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/.claude/",
"sync_triggers": [
"instruction_created",
"instruction_modified",
"instruction_deactivated"
],
"approval_required_for": [
"overwrite",
"delete",
"modify",
"deactivate"
],
"allowed_without_approval": [
"create_new_instruction_with_next_sequential_id"
],
"verification_after_sync": "ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net 'ls -lh /var/www/tractatus/.claude/instruction-history.json && tail -3 /var/www/tractatus/.claude/instruction-history.json'"
},
"active": true,
"notes": "CRITICAL REQUIREMENT 2025-10-12 - Blog system completion: Nearly created inst_025 when it already existed (user intervention prevented). User directive: 'create a rule to NEVER overwrite existing rules unless they are changes to that rule approved by human and ensure the rules are synced between dev and production at all times'. Instruction management protocol: instructions are HIGH-persistence governance data that MUST be protected from accidental modification and kept consistent across environments. Without sync, production sessions would operate under different rules than dev sessions, creating governance drift and unpredictable behavior. This instruction ensures: (1) No accidental overwrites, (2) Human oversight for changes, (3) Consistent governance between environments."
},
{
"id": "inst_028",
"text": "ONLY documentation and research materials MUST be synced to tractatus-framework public GitHub repository at ../tractatus-public. After creating/updating documentation: (1) Manually copy files to ../tractatus-public, (2) Review changes with 'cd ../tractatus-public && git status', (3) Commit with descriptive message, (4) Push to GitHub. EXCLUDE ALL PRODUCTION CODE: src/, tests/, scripts/, public/, systemd/, deployment-quickstart/, package files, .env files, CLAUDE.md, SESSION-HANDOFF files, internal development guides, .claude/ directory, sensitive data. INCLUDE ONLY: docs/ (research, case studies, API documentation - excluding internal docs), README updates, CONTRIBUTING updates, LICENSE. Public repository is DOCUMENTATION ONLY for security reasons - full implementation is proprietary.",
"timestamp": "2025-10-12T09:50:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PROJECT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-12-public-repo-population",
"parameters": {
"public_repo_path": "../tractatus-public",
"sync_script": "scripts/sync-to-public.sh",
"sync_triggers": [
"new_shareable_code",
"documentation_updates",
"deployment_file_changes",
"public_feature_additions"
],
"exclude_patterns": [
"CLAUDE.md",
"SESSION-HANDOFF-*.md",
"*Maintenance_Guide.md",
".claude/",
"NEXT_SESSION*.md",
"PHASE-*-PREP*.md",
"docs/SESSION-*.md",
"docs/FRAMEWORK_FAILURE_*.md",
"docs/SECURITY_AUDIT_REPORT.md",
"docs/governance/MONTHLY-REVIEW-SCHEDULE.md",
"docs/governance/PRIVACY-PRESERVING-ANALYTICS-PLAN.md"
],
"include_directories": [
"src/",
"tests/",
"scripts/",
"public/",
"docs/markdown/",
"docs/api/",
"docs/case-studies/",
"docs/research/",
"docs/governance/ (selective)",
"deployment-quickstart/",
"systemd/"
],
"include_files": [
"package.json",
"package-lock.json",
"README.md",
"CONTRIBUTING.md",
"LICENSE",
".env.example",
".gitignore",
"SETUP_INSTRUCTIONS.md"
],
"workflow_steps": [
"Run sync script",
"Review with git status",
"Commit with descriptive message",
"Push to GitHub"
],
"verification": "curl -s https://github.com/AgenticGovernance/tractatus-framework | grep -c src/"
},
"active": true,
"notes": "SECURITY UPDATE 2025-10-12 - Initially populated public repo with full source code (255 files, 90k+ lines). User reviewed and immediately identified security risk: admin panels, deployment scripts, service configurations, and full source code provide attack surface for bad actors. SECURITY LOCKDOWN: Removed ALL production code (237 files, 79,856 lines). Public repository now DOCUMENTATION ONLY: docs/, README, CONTRIBUTING, LICENSE. Rationale: Framework concepts and research should be public for AI safety community, but production implementation details must remain private to prevent reconnaissance attacks and infrastructure exploitation. Developers can experience framework at https://agenticgovernance.digital and contact john.stroh.nz@pm.me for implementation inquiries. This instruction updated to prevent future syncing of production code."
},
{
"id": "inst_038",
"text": "BEFORE using Edit or Write tools on ANY file (HTML, JS, CSS, config), EXPLICITLY state: 'Running pre-action-check for [filename]' and execute node scripts/pre-action-check.js <action-type> [file-path] '<description>'. If pre-action-check FAILS (exit code 1), STOP immediately and fix violations before proceeding. Never skip pre-action-check - it validates: (1) ContextPressureMonitor recency, (2) Instruction history loaded, (3) Token checkpoints, (4) CSP compliance for HTML/JS files (inst_008), (5) Required framework components used. Skipping pre-action-check is CRITICAL FRAMEWORK FAILURE that can bypass governance rules (CSP, boundary checks, instruction conflicts). Add pre-action-check timestamp to session-state.json for watchdog monitoring.",
"timestamp": "2025-10-12T19:50:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-12-document-review",
"parameters": {
"trigger_tools": [
"Edit",
"Write"
],
"pre_action_command": "node scripts/pre-action-check.js <action-type> [file-path] '<description>'",
"action_types": [
"file-edit",
"database",
"architecture",
"config",
"security",
"values",
"complex"
],
"validates": [
"pressure_check_recency",
"instructions_loaded",
"token_checkpoints",
"csp_compliance",
"framework_components"
],
"fail_behavior": "STOP_immediately_fix_violations",
"csp_enforcement": "Automated detection of inline styles, inline scripts, event handlers (inst_008)",
"session_state_tracking": "Update last_pre_action_check timestamp in session-state.json",
"watchdog_integration": "Enable automated detection if pre-action-check skipped"
},
"active": true,
"notes": "CRITICAL FRAMEWORK GAP 2025-10-12 - User discovered I violated CSP (inst_008) by adding inline styles to docs-app.js during category collapse fix. Root cause: I skipped pre-action-check.js before editing the file. The script would have caught the violations and BLOCKED the action (verified with test). Framework fade: Tool exists and works, but wasn't used. User question: 'why did the rules not pick up the csp violation?' Answer: Because I didn't run pre-action-check. This is a GENERIC FAILURE PATTERN that could bypass multiple rules (CSP, boundary enforcement, instruction conflicts). This instruction makes pre-action-check explicitly required before file modifications, with clear failure protocol. Fourth attempt to fix docs.html categories - need to ensure proper deployment this time."
},
{
"id": "inst_039",
"text": "When processing documents for card presentations or any content updates, MANDATORY audit for: (1) Update all references from 'five services' to 'six services' - PluralisticDeliberationOrchestrator is the 6th service added in Phase 5, (2) Ensure PluralisticDeliberationOrchestrator is properly documented wherever core services are mentioned, (3) Check for rule violations using prohibited absolute language: 'guarantee', 'guarantees', 'always', 'never' (when describing effectiveness), 'impossible', 'ensures 100%', 'eliminates all', 'completely prevents', (4) Verify technical accuracy and currency of all claims - no fabricated statistics or outdated information. This applies to: markdown source files, database document content, public-facing HTML, API documentation, executive briefs, case studies. BEFORE deploying any document updates, search for prohibited terms and outdated service counts.",
"timestamp": "2025-10-12T20:10:00Z",
"quadrant": "STRATEGIC",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-12-card-presentations",
"parameters": {
"mandatory_checks": [
"service_count_accuracy",
"pluralistic_deliberation_mentioned",
"prohibited_language_scan",
"technical_currency"
],
"service_count": {
"incorrect": "five services",
"correct": "six services",
"sixth_service": "PluralisticDeliberationOrchestrator"
},
"prohibited_terms": [
"guarantee",
"guarantees",
"guaranteed",
"always works",
"never fails",
"impossible",
"ensures 100%",
"eliminates all",
"completely prevents",
"perfect protection"
],
"approved_alternatives": [
"designed to reduce",
"helps mitigate",
"reduces risk of",
"supports prevention of",
"intended to minimize",
"architected to limit",
"structurally prevented",
"designed to detect"
],
"search_commands": [
"grep -i 'five service' docs/markdown/*.md",
"grep -i 'guarantee' docs/markdown/*.md",
"grep -i 'always\\|never' docs/markdown/*.md"
],
"applies_to": [
"markdown_sources",
"database_documents",
"public_html",
"api_documentation",
"executive_briefs",
"case_studies",
"blog_posts"
]
},
"related_instructions": [
"inst_016",
"inst_017",
"inst_018"
],
"active": true,
"notes": "CRITICAL CONTENT ACCURACY GAP 2025-10-12 - User identified that most documents still reference 'five services' instead of 'six services'. PluralisticDeliberationOrchestrator was added as 6th service in Phase 5 but existing documentation not updated. Combined with ongoing rule violation checks (inst_016, inst_017) this creates comprehensive content accuracy protocol. User quote: 'very few of the documents refer correctly to the new 6th service! most still refer to 5' and 'we need to actually reexamine the content, not only for rule violations but also for currency'. This instruction ensures systematic content review during card presentation implementation, preventing outdated/inaccurate content from being deployed with improved UI/UX."
},
{
"id": "inst_040",
"text": "When user says 'all' (e.g., 'update all pages', 'fix all instances', 'check all files'), Claude MUST NOT choose to work on a subset. The word 'all' is an EXPLICIT requirement for COMPLETE coverage - every single item in scope must be processed. BEFORE starting work on 'all' requests: (1) Identify the COMPLETE list of items in scope (use find, grep, ls commands), (2) Present the full list to user for confirmation if scope is ambiguous, (3) Work through EVERY item systematically, (4) Verify ALL items were processed before marking task complete. If scope is too large for single session (>20 items), ask user to prioritize or break into smaller batches. NEVER silently skip items or decide 'these N are representative enough'.",
"timestamp": "2025-10-14T13:00:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-14-faq-fixes",
"parameters": {
"trigger_words": [
"all",
"every",
"each"
],
"examples": [
"update all pages",
"fix all instances",
"check all files",
"update every page",
"fix each occurrence"
],
"prohibited_actions": [
"working_on_subset",
"representative_sample",
"partial_completion",
"silent_skipping"
],
"required_actions": [
"identify_complete_scope",
"confirm_if_ambiguous",
"process_every_item",
"verify_complete_coverage"
],
"scope_too_large_threshold": 20,
"large_scope_action": "ask_user_to_prioritize_or_batch"
},
"active": true,
"notes": "IDENTIFIED 2025-10-14 - User directive: 'create a rule that stipulates that when the user says \"all\" as in \"update all...\" Claude may not choose to work on a subset'. Context: Footer standardization where user asked to update all pages, and Claude initially only updated FAQ page footer then used script for remaining pages. User expects 'all' to mean complete coverage without exceptions or representative samples. This prevents pattern where Claude selectively applies changes to subset of items when user explicitly requested universal application."
},
{
"id": "inst_041",
"text": "ALL file uploads (case study submissions, media attachments, document uploads, user-provided files) MUST undergo mandatory malware scanning using sovereign tools before processing or storage. REQUIRED validation pipeline: (1) File type validation using file(1) command - reject mismatched MIME types and extensions, (2) ClamAV antivirus scan with updated virus definitions (minimum daily updates), (3) YARA rule scanning for malware signatures and suspicious patterns, (4) File size limits enforced (max 10MB for documents, 50MB for media), (5) Quarantine suspicious files for manual review - NEVER auto-process flagged content. ALL scans must complete successfully before file is accessible to application logic. Failed scans trigger immediate rejection and security alert logging. Implement in src/middleware/file-security.middleware.js with detailed logging to security audit trail.",
"timestamp": "2025-10-14T01:45:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-14-security-vetting",
"parameters": {
"trigger_conditions": [
"file_upload",
"document_submission",
"media_attachment",
"case_study_upload",
"any_external_file"
],
"sovereign_tools": {
"file_type_validation": "file(1) - UNIX file command",
"antivirus": "ClamAV (clamscan/clamdscan)",
"pattern_matching": "YARA rules engine",
"update_frequency": "ClamAV definitions: minimum daily"
},
"validation_pipeline": [
"file_type_validation",
"mime_type_verification",
"clamav_scan",
"yara_scan",
"size_limit_check"
],
"size_limits": {
"documents": "10MB",
"media": "50MB",
"default": "5MB"
},
"rejection_criteria": [
"mime_type_mismatch",
"virus_detected",
"malware_signature_match",
"size_exceeded",
"suspicious_patterns"
],
"quarantine_directory": "/var/quarantine/tractatus",
"security_logging": "src/utils/security-logger.js",
"implementation_file": "src/middleware/file-security.middleware.js"
},
"active": true,
"notes": "SECURITY REQUIREMENT 2025-10-14 - User directive: 'Create a set of tractatus permanent strategic rules that ensures any external input to the website or incoming mail or case study submissions etc are rigorously vetted for malware, viruses, sleeper code or any other bad actor infiltration attempts.' Part 1 of comprehensive security vetting framework. File uploads are primary attack vector for malware injection. Sovereign tools (ClamAV, YARA, file(1)) are open-source, auditable, and under organizational control - no reliance on external services or proprietary scanning APIs. Multi-layer validation creates defense in depth: type validation catches file extension spoofing, ClamAV catches known malware, YARA catches suspicious patterns and zero-days."
},
{
"id": "inst_042",
"text": "ALL email attachments and incoming mail to system addresses (media inquiries, case submissions, contact forms processed via email) MUST be scanned using sovereign email security stack before delivery to application. REQUIRED email security pipeline: (1) SpamAssassin content filtering with custom rules for governance domain (minimum score 5.0 = spam), (2) amavisd-new integration for virus scanning (ClamAV backend), (3) Attachment type restrictions - only allow: PDF, TXT, MD, DOC/DOCX, images (PNG/JPG). Block: executables, scripts, archives, macros, (4) DKIM/SPF/DMARC validation for sender authentication, (5) Rate limiting per sender (max 10 emails/hour from unknown senders), (6) Suspicious attachments quarantined to /var/quarantine/email/ with alert to admin. Configure postfix/dovecot with these filters. ALL blocked emails logged to security audit trail with sender IP, timestamp, rejection reason. Implement monitoring dashboard for security team.",
"timestamp": "2025-10-14T01:45:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-14-security-vetting",
"parameters": {
"trigger_conditions": [
"incoming_email",
"email_attachments",
"contact_form_email",
"media_inquiry_email",
"case_submission_email"
],
"sovereign_tools": {
"spam_filter": "SpamAssassin",
"virus_scanning": "amavisd-new with ClamAV backend",
"mail_server": "postfix/dovecot",
"authentication": "OpenDKIM, opendmarc"
},
"email_pipeline": [
"spamassassin_filtering",
"dkim_spf_dmarc_validation",
"amavisd_virus_scan",
"attachment_type_validation",
"rate_limiting_check"
],
"allowed_attachments": [
"application/pdf",
"text/plain",
"text/markdown",
"application/msword",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"image/png",
"image/jpeg"
],
"blocked_attachments": [
"executables (.exe, .bat, .cmd, .sh)",
"scripts (.js, .vbs, .ps1, .py)",
"archives (.zip, .rar, .tar, .gz)",
"macros (macro-enabled documents)",
"suspicious extensions (.scr, .pif, .com)"
],
"spamassassin_config": {
"required_score": "5.0",
"custom_rules": "/etc/spamassassin/local.cf",
"auto_learn": true
},
"rate_limiting": {
"unknown_senders": "10 emails per hour",
"known_senders": "100 emails per hour",
"implementation": "postfix policyd-weight"
},
"quarantine_directory": "/var/quarantine/email",
"monitoring": "security dashboard for blocked emails"
},
"active": true,
"notes": "SECURITY REQUIREMENT 2025-10-14 - Part 2 of comprehensive security vetting framework. Email is secondary attack vector - phishing, malware attachments, social engineering attempts. Sovereign email stack (SpamAssassin, amavisd-new, postfix) provides complete control over filtering rules and logging. DKIM/SPF/DMARC prevents sender spoofing. Attachment restrictions prevent executable delivery. Rate limiting prevents spam floods and automated attacks. This creates layered defense for email-based threats while maintaining full auditability and control of security infrastructure."
},
{
"id": "inst_043",
"text": "ALL user input from web forms (contact forms, case submissions, media inquiries, comment fields, search inputs) MUST undergo rigorous sanitization and validation BEFORE processing or storage. MANDATORY validation layers: (1) Input length limits enforced (configurable per field, default max 5000 chars), (2) HTML sanitization using DOMPurify (sovereign JS library) - strip ALL HTML tags except safe whitelist for markdown fields, (3) SQL injection prevention via parameterized queries ONLY (NEVER string concatenation in MongoDB queries), (4) NoSQL injection prevention - validate all user input against expected data types and patterns before database operations, (5) XSS prevention - Content Security Policy enforcement (inst_008) + output encoding, (6) CSRF protection on all POST/PUT/DELETE endpoints using signed tokens. Implement in src/middleware/input-validation.middleware.js with comprehensive logging. Use validator.js library for email, URL, and data format validation. Rate limit form submissions: 5 requests per minute per IP.",
"timestamp": "2025-10-14T01:45:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-14-security-vetting",
"parameters": {
"trigger_conditions": [
"form_submission",
"user_input",
"search_query",
"contact_form",
"case_submission",
"media_inquiry",
"comment_field",
"any_external_text_input"
],
"sovereign_tools": {
"html_sanitization": "DOMPurify (client + server)",
"validation_library": "validator.js",
"parameterized_queries": "MongoDB driver with prepared statements",
"csrf_protection": "csurf middleware"
},
"validation_pipeline": [
"length_limit_check",
"data_type_validation",
"html_sanitization",
"nosql_injection_check",
"xss_pattern_detection",
"csrf_token_validation"
],
"input_limits": {
"default_max_length": 5000,
"email": 254,
"url": 2048,
"phone": 20,
"name": 100,
"title": 200,
"description": 5000,
"case_study": 50000
},
"html_sanitization": {
"default": "strip_all_html",
"markdown_fields": "allow_safe_whitelist",
"safe_tags": [
"p",
"br",
"strong",
"em",
"ul",
"ol",
"li",
"a",
"code",
"pre"
],
"blocked_tags": [
"script",
"iframe",
"object",
"embed",
"style",
"link"
]
},
"injection_prevention": {
"sql": "parameterized_queries_only",
"nosql": "type_validation_before_query",
"mongodb_unsafe_operators": [
"$where",
"mapReduce",
"eval"
],
"validation": "mongoose_schema_validation"
},
"xss_prevention": [
"csp_enforcement (inst_008)",
"output_encoding",
"dompurify_sanitization",
"no_dangerouslySetInnerHTML"
],
"csrf_protection": {
"implementation": "csurf middleware",
"token_rotation": "per_session",
"applies_to": [
"POST",
"PUT",
"DELETE",
"PATCH"
]
},
"rate_limiting": {
"form_submissions": "5 requests per minute per IP",
"search_queries": "20 requests per minute per IP",
"implementation": "express-rate-limit"
},
"implementation_file": "src/middleware/input-validation.middleware.js",
"logging": "security audit trail for rejected inputs"
},
"active": true,
"notes": "SECURITY REQUIREMENT 2025-10-14 - Part 3 of comprehensive security vetting framework. Web form inputs are most common attack vector for XSS, injection attacks, and data exfiltration. DOMPurify is sovereign (open-source, client+server capable) and industry-standard for HTML sanitization. Parameterized queries prevent SQL/NoSQL injection. CSP (inst_008) provides defense in depth for XSS. CSRF tokens prevent cross-site request forgery. Rate limiting prevents automated form spam and brute force attempts. Multi-layer validation creates defense in depth: input validation, sanitization, parameterized queries, output encoding, CSP enforcement."
},
{
"id": "inst_044",
"text": "ALL HTTP responses MUST include comprehensive security headers to prevent common web attacks and provide defense in depth. MANDATORY security headers: (1) Content-Security-Policy with strict directives (enforces inst_008 at HTTP level), (2) X-Content-Type-Options: nosniff - prevent MIME type sniffing attacks, (3) X-Frame-Options: DENY - prevent clickjacking via iframes, (4) X-XSS-Protection: 1; mode=block - enable browser XSS filter, (5) Strict-Transport-Security: max-age=31536000; includeSubDomains; preload - enforce HTTPS, (6) Referrer-Policy: strict-origin-when-cross-origin - limit referrer leakage, (7) Permissions-Policy to restrict dangerous browser features. Implement in src/middleware/security-headers.middleware.js applied to ALL routes. CSP directives must match inst_008: script-src 'self', no inline scripts, no unsafe-eval. Regularly audit CSP violations via report-uri endpoint. Monitor SecurityHeaders.com grade (target: A+).",
"timestamp": "2025-10-14T01:45:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-14-security-vetting",
"parameters": {
"trigger_conditions": [
"all_http_responses",
"every_route",
"api_responses",
"static_files",
"error_pages"
],
"mandatory_headers": {
"Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'; upgrade-insecure-requests; block-all-mixed-content",
"X-Content-Type-Options": "nosniff",
"X-Frame-Options": "DENY",
"X-XSS-Protection": "1; mode=block",
"Strict-Transport-Security": "max-age=31536000; includeSubDomains; preload",
"Referrer-Policy": "strict-origin-when-cross-origin",
"Permissions-Policy": "geolocation=(), microphone=(), camera=(), payment=()"
},
"csp_directives": {
"default-src": "'self'",
"script-src": "'self'",
"style-src": "'self' 'unsafe-inline'",
"img-src": "'self' data: https:",
"font-src": "'self' https://fonts.gstatic.com",
"connect-src": "'self'",
"frame-ancestors": "'none'",
"base-uri": "'self'",
"form-action": "'self'",
"upgrade-insecure-requests": true,
"block-all-mixed-content": true,
"report-uri": "/api/csp-violations"
},
"csp_violations_endpoint": {
"route": "/api/csp-violations",
"logging": "security audit trail",
"monitoring": "alert on repeated violations"
},
"hsts_preload": {
"status": "required for production",
"submission": "https://hstspreload.org/",
"prerequisites": [
"valid_certificate",
"https_on_all_subdomains",
"redirect_http_to_https"
]
},
"implementation_file": "src/middleware/security-headers.middleware.js",
"application_point": "app.use(securityHeadersMiddleware) - before all routes",
"monitoring": {
"tool": "SecurityHeaders.com",
"target_grade": "A+",
"audit_frequency": "weekly"
},
"related_tools": {
"helmet_js": "optional convenience wrapper",
"manual_implementation": "preferred for full control"
}
},
"related_instructions": [
"inst_008"
],
"active": true,
"notes": "SECURITY REQUIREMENT 2025-10-14 - Part 4 of comprehensive security vetting framework. HTTP security headers provide browser-level defense against common web attacks. CSP enforcement at HTTP level (inst_008 enforces at code level, inst_044 enforces at protocol level) creates defense in depth. HSTS prevents SSL stripping attacks. X-Frame-Options prevents clickjacking. X-Content-Type-Options prevents MIME confusion attacks. These headers are 'sovereign' in the sense that they're implemented entirely within our control (no external dependencies), enforce security policies at protocol level, and provide defense even if application-level protections fail. CSP violation reporting provides early warning of attack attempts or policy violations."
},
{
"id": "inst_045",
"text": "ALL API endpoints MUST implement rate limiting, authentication requirements, and input validation to prevent automated attacks, brute force attempts, and API abuse. MANDATORY protections: (1) Rate limiting with express-rate-limit: public endpoints 100 req/15min per IP, authenticated endpoints 1000 req/15min per user, admin endpoints 50 req/15min per admin, (2) Authentication middleware for sensitive endpoints - JWT validation with short expiry (15min access, 7day refresh), (3) IP-based blocking after repeated rate limit violations (10 violations in 1 hour = 24 hour block), (4) Request validation for all POST/PUT/PATCH - reject requests with unexpected fields or malformed JSON, (5) Response sanitization - NEVER expose stack traces, internal paths, or sensitive errors to clients (inst_013), (6) API key rotation for service-to-service communication every 90 days. Implement monitoring for unusual API patterns: rapid endpoint enumeration, repeated 401s, large payloads, unusual user agents. Log all rate limit violations and authentication failures to security audit trail.",
"timestamp": "2025-10-14T01:45:00Z",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-14-security-vetting",
"parameters": {
"trigger_conditions": [
"all_api_endpoints",
"public_routes",
"authenticated_routes",
"admin_routes",
"service_to_service_communication"
],
"rate_limiting": {
"public_endpoints": "100 requests per 15 minutes per IP",
"authenticated_endpoints": "1000 requests per 15 minutes per user",
"admin_endpoints": "50 requests per 15 minutes per admin",
"implementation": "express-rate-limit",
"storage": "Redis for distributed rate limiting",
"violation_threshold": "10 violations in 1 hour = 24 hour IP block"
},
"authentication": {
"mechanism": "JWT (JSON Web Tokens)",
"access_token_expiry": "15 minutes",
"refresh_token_expiry": "7 days",
"algorithm": "HS256",
"secret_rotation": "every 90 days",
"middleware": "src/middleware/auth.middleware.js"
},
"endpoint_classification": {
"public": [
"/health",
"/api/documents",
"/api/blog"
],
"authenticated": [
"/api/cases",
"/api/media",
"/api/koha"
],
"admin": [
"/api/admin/*",
"/api/governance/*"
]
},
"input_validation": {
"reject_unexpected_fields": true,
"reject_malformed_json": true,
"max_payload_size": "1MB",
"content_type_enforcement": "application/json for POST/PUT/PATCH"
},
"response_sanitization": {
"production_mode": "hide_stack_traces",
"hide_internal_paths": true,
"generic_error_messages": true,
"error_codes_only": "specific details logged, not exposed",
"relates_to": "inst_013"
},
"service_to_service": {
"api_key_rotation": "every 90 days",
"mutual_tls": "consider for high security services",
"key_storage": "environment variables, not in code"
},
"monitoring_alerts": [
"rapid_endpoint_enumeration (>50 unique endpoints in 1 minute)",
"repeated_401_errors (>10 from single IP in 5 minutes)",
"large_payloads (>10MB)",
"unusual_user_agents (automated scanners)",
"rate_limit_violations (repeated from same IP)",
"authentication_failures (>5 failed attempts in 5 minutes)"
],
"ip_blocking": {
"automatic_block": "10 rate limit violations in 1 hour",
"block_duration": "24 hours",
"whitelist": "monitoring services, known good IPs",
"implementation": "express-slow-down + custom blocking middleware",
"storage": "Redis for distributed blocking"
},
"logging": {
"security_audit_trail": "all violations, failures, blocks",
"log_fields": [
"timestamp",
"ip",
"endpoint",
"method",
"user_agent",
"violation_type",
"user_id (if authenticated)"
]
},
"implementation_files": [
"src/middleware/rate-limit.middleware.js",
"src/middleware/auth.middleware.js",
"src/middleware/api-validation.middleware.js",
"src/utils/security-logger.js"
]
},
"related_instructions": [
"inst_013"
],
"active": true,
"notes": "SECURITY REQUIREMENT 2025-10-14 - Part 5 of comprehensive security vetting framework. API endpoints are primary targets for automated attacks, brute force attempts, credential stuffing, and reconnaissance. Rate limiting prevents abuse and DoS attacks. JWT authentication with short expiry limits impact of token theft. IP blocking prevents persistent attackers. Request validation prevents injection attacks and malformed input exploitation. Response sanitization (inst_013) prevents information disclosure. Monitoring unusual patterns provides early warning of attacks. This creates defense in depth for API security: rate limiting (prevent volume), authentication (verify identity), input validation (prevent injection), response sanitization (prevent info disclosure), monitoring (detect attacks)."
},
{
"id": "inst_046",
"text": "ALL security events (file upload rejections, email blocks, input validation failures, rate limit violations, authentication failures, CSP violations, suspicious patterns) MUST be logged to centralized security audit trail with comprehensive monitoring and alerting. MANDATORY security monitoring: (1) Centralized logging to /var/log/tractatus/security-audit.log with rotation (daily, keep 90 days), (2) Real-time monitoring dashboard showing: rejected uploads, blocked emails, rate limit violations, failed authentications, CSP violations, IP blocks, (3) Alert thresholds: >10 violations from single IP in 1 hour = immediate email alert, >100 violations globally in 1 hour = potential attack underway alert, (4) Weekly security reports: summary of all security events, top violating IPs, attack patterns identified, (5) Integration with fail2ban for automatic IP blocking across services. Implement security dashboard at /admin/security-monitoring.html (admin auth required). Log format: JSON with timestamp, event_type, source_ip, user_id, endpoint, violation_details, action_taken. Use sovereign log analysis tools: grep, awk, custom scripts (no external log aggregation services unless encrypted).",
"timestamp": "2025-10-14T01:45:00Z",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"verification_required": "MANDATORY",
"explicitness": 1.0,
"source": "user",
"session_id": "2025-10-14-security-vetting",
"parameters": {
"trigger_conditions": [
"any_security_event",
"file_upload_rejection",
"email_block",
"input_validation_failure",
"rate_limit_violation",
"authentication_failure",
"csp_violation",
"suspicious_pattern_detection",
"ip_block_applied"
],
"security_events": [
"file_upload_rejected",
"malware_detected",
"email_blocked",
"spam_filtered",
"input_sanitization_applied",
"injection_attempt_blocked",
"rate_limit_exceeded",
"authentication_failed",
"csp_violation_reported",
"ip_blocked",
"unusual_api_pattern"
],
"centralized_logging": {
"log_file": "/var/log/tractatus/security-audit.log",
"rotation": "daily",
"retention": "90 days",
"format": "JSON",
"fields": [
"timestamp",
"event_type",
"source_ip",
"user_id",
"endpoint",
"user_agent",
"violation_details",
"action_taken",
"severity"
]
},
"monitoring_dashboard": {
"route": "/admin/security-monitoring.html",
"authentication": "admin_only",
"metrics": [
"rejected_uploads_count",
"blocked_emails_count",
"rate_limit_violations",
"failed_authentications",
"csp_violations",
"active_ip_blocks",
"attack_patterns_identified"
],
"time_ranges": [
"last_hour",
"last_24_hours",
"last_7_days",
"last_30_days"
]
},
"alert_thresholds": {
"single_ip_violations": {
"threshold": "10 violations in 1 hour",
"action": "immediate email alert to admin",
"includes": "IP address, violation types, affected endpoints"
},
"global_violations": {
"threshold": "100 violations in 1 hour",
"action": "potential attack alert",
"includes": "event summary, top violating IPs, attack pattern analysis"
},
"authentication_failures": {
"threshold": "5 failures in 5 minutes for single user",
"action": "account lockout + alert"
},
"critical_events": {
"malware_detected": "immediate alert",
"admin_account_compromise_attempt": "immediate alert",
"data_exfiltration_pattern": "immediate alert"
}
},
"reporting": {
"weekly_security_report": {
"recipients": [
"admin@tractatus.local",
"security@tractatus.local"
],
"includes": [
"security_events_summary",
"top_violating_ips",
"attack_patterns_identified",
"blocked_threats_count",
"recommendations"
]
}
},
"fail2ban_integration": {
"enabled": true,
"log_parsing": "parse security-audit.log for IP violations",
"ban_duration": "24 hours",
"ban_action": "iptables block + log",
"whitelist": "monitoring services, admin IPs"
},
"sovereign_analysis_tools": [
"grep",
"awk",
"sed",
"jq (for JSON)",
"custom shell scripts",
"NO external log aggregation (unless encrypted)"
],
"implementation_files": [
"src/utils/security-logger.js",
"public/admin/security-monitoring.html",
"public/js/admin/security-monitoring.js",
"scripts/generate-security-report.js",
"/etc/fail2ban/filter.d/tractatus.conf"
]
},
"active": true,
"notes": "SECURITY REQUIREMENT 2025-10-14 - Part 6 of comprehensive security vetting framework. Comprehensive logging and monitoring are essential for: (1) detecting attacks in progress, (2) forensic analysis after incidents, (3) compliance and audit requirements, (4) continuous improvement of security rules. Centralized logging provides single source of truth for all security events. Real-time monitoring dashboard provides visibility for security team. Alert thresholds enable rapid response to attacks. fail2ban integration provides automated defense. Sovereign tools (grep, awk, jq) ensure full control over log analysis without external dependencies. 90-day retention balances forensic needs with storage costs. This completes the 6-layer security vetting framework: file uploads (inst_041), email (inst_042), form inputs (inst_043), HTTP headers (inst_044), API protection (inst_045), monitoring/alerting (inst_046)."
}
],
"stats": {
"total_instructions": 46,
"active_instructions": 46,
"by_quadrant": {
"STRATEGIC": 7,
"OPERATIONAL": 19,
"TACTICAL": 1,
"SYSTEM": 15,
"STOCHASTIC": 0
},
"by_persistence": {
"HIGH": 42,
"MEDIUM": 2,
"LOW": 0,
"VARIABLE": 0
}
}
}
Reference in a new issue View git blame Copy permalink