8b9bb89797
Priority 2 Implementation: - Extract inline JavaScript to /public/js/koha-transparency.js (CSP compliant) - Add Chart.js 4.4.0 for visual allocation breakdown (doughnut chart) - Implement CSV export functionality with comprehensive transparency report - Link transparency dashboard from homepage footer (Support This Work section) - Deploy to production: https://agenticgovernance.digital/koha/transparency.html Homepage Enhancement: - Add "Support This Work" section to footer with donation links - Include Blog link in Community section Governance Framework: - Add inst_022: Automated deployment permission correction requirement - Addresses recurring permission issues (0700 directories causing 403 errors) - Mandates rsync --chmod=D755,F644 or post-deployment automation - Related to inst_020, but shifts from validation to prevention Technical Details: - Responsive design with Tailwind breakpoints - Auto-refresh metrics every 5 minutes - WCAG-compliant accessibility features - Minimal footprint: ~8.5KB JavaScript Fixes: - /public/koha/ directory permissions (755 required for nginx) - Added inst_022 to prevent future permission issues 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
449 lines
25 KiB
JSON
449 lines
25 KiB
JSON
{
|
|
"version": "1.0",
|
|
"last_updated": "2025-10-11T04:05: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.90,
|
|
"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.90,
|
|
"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.90,
|
|
"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."
|
|
}
|
|
],
|
|
"stats": {
|
|
"total_instructions": 22,
|
|
"active_instructions": 22,
|
|
"by_quadrant": {
|
|
"STRATEGIC": 6,
|
|
"OPERATIONAL": 6,
|
|
"TACTICAL": 1,
|
|
"SYSTEM": 9,
|
|
"STOCHASTIC": 0
|
|
},
|
|
"by_persistence": {
|
|
"HIGH": 20,
|
|
"MEDIUM": 2,
|
|
"LOW": 0,
|
|
"VARIABLE": 0
|
|
}
|
|
}
|
|
}
|