create-living-architecture 1.1.0 → 2.0.0

package/src/app/installer-workflow.js

@@ -0,0 +1,56 @@
+/**
+ * installer-workflow.js - R2 Application
+ * Orchestrates: validate -> plan -> scaffold -> hook -> commit.
+ */
+
+const path     = require('path');
+const { execSync } = require('child_process');
+const logic    = require('../domain/installer-logic');
+const io       = require('../exec/installer-io');
+
+function run(projectName) {
+    // 1. Validate
+    const validation = logic.validateProjectName(projectName);
+    if (!validation.valid) {
+        return { success: false, error: validation.error };
+    }
+
+    // 2. Check target doesn't already exist
+    if (io.exists(projectName)) {
+        return { success: false, error: `Directory '${projectName}' already exists` };
+    }
+
+    // 3. Build plan
+    const laSourceDir = path.resolve(__dirname, '../..');
+    const plan = logic.buildScaffoldPlan(projectName, laSourceDir);
+
+    // 4. Copy LA structure
+    io.copyDir(path.join(laSourceDir, 'src'),          path.join(plan.targetDir, 'src'));
+    io.copyDir(path.join(laSourceDir, '.living-arch'), path.join(plan.targetDir, '.living-arch'));
+
+    // 5. Init git
+    execSync(`git init ${plan.targetDir}`, { stdio: 'pipe' });
+
+    // 6. Hook up pre-commit and commit-msg
+    const hooksDir   = path.join(plan.targetDir, 'src/contract/hooks');
+    const gitHooksDir = path.join(plan.targetDir, '.git/hooks');
+
+    io.chmodExec(path.join(hooksDir, 'pre-commit'));
+    io.chmodExec(path.join(hooksDir, 'commit-msg'));
+
+    const preCommitSrc = path.resolve(path.join(hooksDir, 'pre-commit'));
+    const commitMsgSrc = path.resolve(path.join(hooksDir, 'commit-msg'));
+
+    io.writeFile(path.join(gitHooksDir, 'pre-commit'), `#!/bin/bash\n"${preCommitSrc}" "$@"\n`);
+    io.writeFile(path.join(gitHooksDir, 'commit-msg'), `#!/bin/bash\n"${commitMsgSrc}" "$@"\n`);
+    io.chmodExec(path.join(gitHooksDir, 'pre-commit'));
+    io.chmodExec(path.join(gitHooksDir, 'commit-msg'));
+
+    // 7. Initial commit — no F-tag, scaffold is not a feature
+    execSync('git add .', { cwd: plan.targetDir, stdio: 'pipe' });
+    execSync('git commit --no-verify -m "LA v2.0 scaffold"', { cwd: plan.targetDir, stdio: 'pipe' });
+
+    return { success: true, projectName, targetDir: plan.targetDir };
+}
+
+module.exports = { run };

package/src/app/validation-workflow.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+validation-workflow.py - R2 Orchestration
+Coordinates all R1 validators with R4 I/O.
+R4 reads files, R1 validates content, R2 assembles results.
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+
+from exec import git_io, file_io
+from domain import (
+    validate_f_tags,
+    validate_execution,
+    validate_operations,
+    validate_r_layers,
+    validate_changes,
+    la_output,
+)
+from domain.config_loader import get_module_from_filepath
+
+
+def run_all_validators():
+    commit_msg = git_io.get_commit_message()
+    if not commit_msg:
+        return {'error': 'No commit message found', 'overall_valid': False}
+
+    staged_files = git_io.get_staged_files()
+
+    results = {
+        'commit_message': commit_msg,
+        'staged_files':   staged_files,
+        'validations':    {}
+    }
+
+    # R0-driven validators (commit message only)
+    results['validations']['changes'] = validate_changes.validate(commit_msg)
+    results['validations']['f_tags']  = validate_f_tags.validate(commit_msg)
+
+    # Per-file validators — R4 reads, R1 checks
+    exec_results   = []
+    qc_results     = []
+    layer_violations = []
+
+    for filepath in staged_files:
+        if not filepath.endswith(('.py', '.js')):
+            continue
+
+        content = file_io.read_file(filepath)
+        if content is None:
+            continue
+
+        exec_results.append(validate_execution.validate(filepath, content))
+        qc_results.append(validate_operations.validate(filepath, content))
+        layer_violations.extend(validate_r_layers.check_file(filepath, content))
+
+    results['validations']['execution'] = {
+        'valid': all(r.get('valid', True) for r in exec_results),
+        'files': exec_results
+    }
+
+    results['validations']['qc'] = {
+        'valid':      all(r.get('valid', True) for r in qc_results),
+        'files':      qc_results,
+        'violations': [v for r in qc_results for v in r.get('violations', [])]
+    }
+
+    results['validations']['r_layers'] = {
+        'valid':      len(layer_violations) == 0,
+        'violations': layer_violations
+    }
+
+    # Module detection
+    modules_touched = set()
+    for filepath in staged_files:
+        module = get_module_from_filepath(filepath)
+        if module:
+            modules_touched.add(module)
+    results['modules_touched'] = sorted(modules_touched)
+
+    results['overall_valid'] = all(
+        v.get('valid', True) for v in results['validations'].values()
+    )
+
+    return results
+
+
+def validate_files(filepaths):
+    """
+    Run execution + QC validators against a list of files.
+    Used by network-scan (R3) to get real results for scan_feature.
+    """
+    exec_valid = True
+    qc_valid   = True
+    qc_violations = []
+
+    for filepath in filepaths:
+        content = file_io.read_file(filepath)
+        if content is None:
+            continue
+        e = validate_execution.validate(filepath, content)
+        q = validate_operations.validate(filepath, content)
+        if not e.get('valid', True):
+            exec_valid = False
+        if not q.get('valid', True):
+            qc_valid = False
+            qc_violations.extend(q.get('violations', []))
+
+    return {
+        'execution': {'valid': exec_valid},
+        'qc':        {'valid': qc_valid, 'violations': qc_violations}
+    }
+
+
+def format_output(results):
+    lines = []
+    lines.append(la_output.header('LIVING ARCHITECTURE'))
+    lines.append(f"  {results['commit_message']}")
+    lines.append('')
+
+    if results.get('modules_touched'):
+        lines.append(f"  Modules: {', '.join(results['modules_touched'])}")
+        lines.append('')
+
+    # R-layers
+    r_val = results['validations']['r_layers']
+    if r_val['valid']:
+        lines.append(f"  {'R-layers':14}{la_output.ok('')}")
+    else:
+        n = len(r_val['violations'])
+        suffix = 's' if n != 1 else ''
+        lines.append(f"  {'R-layers':14}{la_output.err(f'{n} violation{suffix}')}") 
+
+    # F-tag
+    f_tag_val = results['validations']['f_tags']
+    if f_tag_val.get('valid'):
+        f_tag_name = f_tag_val.get('f_tag', 'F-unknown')
+        if f_tag_val.get('complete'):
+            lines.append(f"  {f_tag_name:14}{la_output.ok('')}")
+        else:
+            missing = ', '.join(f_tag_val.get('layers_missing', []))
+            lines.append(f"  {f_tag_name:14}{la_output.warn(f'missing {missing}')}")
+    else:
+        lines.append(f"  {'F-tag':14}{la_output.err(f_tag_val.get('error', 'Invalid'))}")
+
+    # Execution
+    exec_val = results['validations']['execution']
+    lines.append(f"  {'Execution':14}{la_output.ok('') if exec_val['valid'] else la_output.err('')}")
+
+    # QC
+    qc_val = results['validations']['qc']
+    if qc_val['valid']:
+        lines.append(f"  {'QC':14}{la_output.ok('')}")
+    else:
+        violations = qc_val.get('violations', [])
+        lines.append(f"  {'QC':14}{la_output.err(violations[0] if violations else 'violation')}")
+
+    # C-code
+    c_val = results['validations']['changes']
+    if c_val.get('valid'):
+        lines.append(f"  {'C-code':14}{la_output.ok(c_val.get('c_code', ''))}")
+    else:
+        lines.append(f"  {'C-code':14}{la_output.err(c_val.get('error', 'Invalid'))}")
+
+    lines.append('')
+    if results['overall_valid']:
+        lines.append(f"  {la_output.ok(la_output.bold('COMMIT ALLOWED'))}")
+    else:
+        lines.append(f"  {la_output.err(la_output.bold('BLOCKED: Fix errors to proceed'))}")
+    lines.append('')
+    lines.append(la_output.divider())
+
+    return '\n'.join(lines)
+
+
+if __name__ == '__main__':
+    results = run_all_validators()
+
+    if 'error' in results:
+        sys.exit(0)
+
+    print(format_output(results))
+    sys.exit(0 if results['overall_valid'] else 1)

package/src/config/SYSTEM.md

@@ -0,0 +1,58 @@
+# Living Architecture - Project Guide
+
+## R-Layer Gravity
+
+- **R0** `src/config/` - Pure configuration
+- **R1** `src/domain/` - Pure business logic
+- **R2** `src/app/` - Orchestration & workflows
+- **R3** `src/contract/` - API boundaries & interfaces
+- **R4** `src/exec/` - I/O operations
+
+## Commit Format
+
+```
+[F-feature-name/R#/C#] Description
+```
+
+**Examples:**
+- `[F-login/R1/C2] Add password validation logic`
+- `[F-payments/R4/C2] Add Stripe API integration`
+- `[F-checkout/R2/C1] Refactor cart workflow`
+
+## Change Codes (C#)
+
+- **C1** - Internal refactoring
+- **C2** - New feature
+- **C3** - API/contract change
+- **C4** - R-layer restructure
+- **C5** - Migration
+
+## Module Naming Convention (Optional)
+
+Group related code across ALL R-layers using module prefixes:
+
+**Format:** `{module}-{component}.ext`
+
+**Example - Auth module:**
+```
+R0/config/auth-rules.json
+R1/domain/auth-login.py
+R2/app/auth-workflow.py
+R3/contract/auth-api.js
+R4/exec/auth-db.py
+```
+
+**Benefits:**
+- Visual grouping across layers
+- Easy searching: `find . -name "auth-*"`
+- Validators display module info
+- **Entirely optional** - use if helpful
+
+## Commands
+
+```bash
+network-scan              # See all features
+network-scan F-login      # Analyze one feature
+```
+
+Let code settle at its natural gravity level.

package/src/config/changes.json

@@ -0,0 +1,11 @@
+{
+  "version": "2.0.0",
+  "codes": {
+    "C1": "Internal - refactor, no external change",
+    "C2": "Feature - new functionality",
+    "C3": "Contract - API/interface change",
+    "C4": "Structure - R-layer reorganization",
+    "C5": "Migration - data/dependency update"
+  },
+  "format": "C[1-5]"
+}

package/src/config/execution.json

@@ -0,0 +1,9 @@
+{
+  "version": "2.0.0",
+  "patterns": {
+    "io_ownership": "Single owner per I/O channel",
+    "state_machines": "Complete state transitions",
+    "coordination": "Single R2 orchestrator per path",
+    "flow_paths": "No circular dependencies"
+  }
+}

package/src/config/f-tags.json

@@ -0,0 +1,12 @@
+{
+  "version": "2.0.0",
+  "format": {
+    "pattern": "F-[a-z][a-z0-9-]*",
+    "description": "Kebab-case, starts with lowercase letter"
+  },
+  "completeness": {
+    "required_layers": ["R1", "R3", "R4"],
+    "optional_layers": ["R0", "R2"],
+    "description": "Complete feature needs logic (R1), interface (R3), and I/O (R4)"
+  }
+}

package/src/config/interfaces.json

@@ -0,0 +1,16 @@
+{
+  "version": "2.0.0",
+  "enabled": false,
+  "description": "Interface contracts between R-layers (manual documentation)",
+  "convention": {
+    "format": "Document expected inputs/outputs between layers",
+    "examples": [
+      "R2 calls R1: login(username, password) -> Session",
+      "R3 calls R2: checkout() -> OrderConfirmation"
+    ]
+  },
+  "validation": {
+    "enforce_contracts": false,
+    "note": "Interfaces are documented, not enforced. Use for human/AI reference."
+  }
+}

package/src/config/modules.json

@@ -0,0 +1,19 @@
+{
+  "version": "2.0.0",
+  "enabled": true,
+  "convention": {
+    "format": "{module}-{component}.ext",
+    "description": "Group related code across R-layers with module prefix",
+    "examples": [
+      "auth-login.py",
+      "auth-session.py",
+      "payment-process.py",
+      "cart-add.py"
+    ]
+  },
+  "rules": {
+    "enforce_boundaries": false,
+    "warn_cross_module": true,
+    "display_in_output": true
+  }
+}

package/src/config/operations.json

@@ -0,0 +1,272 @@
+{
+  "version": "2.0.0",
+  "specification": "operational.json",
+  "enforcement_mode": "blocking",
+  
+  "operational_dimensions": {
+    "O1_access_control": {
+      "name": "Access Control & Abuse Prevention",
+      "scope": "all external access points",
+      "mandatory_checks": [
+        {
+          "check": "authentication_required",
+          "rule": "All external access SHALL be authenticated or explicitly marked public",
+          "enforcement_layer": "R3_contract"
+        },
+        {
+          "check": "authorization_enforcement",
+          "rule": "Authorization SHALL be enforced at Application layer (R2)",
+          "enforcement_layer": "R2_application"
+        },
+        {
+          "check": "no_business_logic_in_auth",
+          "rule": "Execution layer SHALL NOT encode business permission logic",
+          "violation": "Auth checks in controllers acceptable; auth rules are not"
+        }
+      ]
+    },
+
+    "O2_traffic_management": {
+      "name": "Traffic Management",
+      "scope": "all system boundaries",
+      "mandatory_properties": [
+        {
+          "property": "rate_limiting",
+          "requirement": "SHALL exist at system boundaries",
+          "identity_aware": true,
+          "supported_identities": ["user", "token", "ip", "api_key"],
+          "state_location": "R4_execution"
+        },
+        {
+          "property": "throttling",
+          "requirement": "SHALL prevent accidental DoS",
+          "notes": "Protects against AI-generated infinite loops"
+        },
+        {
+          "property": "quotas",
+          "requirement": "SHALL be configurable per identity type"
+        },
+        {
+          "property": "burst_control",
+          "requirement": "SHALL define maximum burst size"
+        }
+      ],
+      "code_pattern_example": {
+        "violation": "await fetch(externalAPI)",
+        "compliant": "await rateLimiter.wrap(() => fetch(externalAPI, {timeout: 5000}), {maxRetries: 3, identity: userId})"
+      }
+    },
+
+    "O3_reliability": {
+      "name": "Reliability & Fault Tolerance",
+      "scope": "all external calls and stateful operations",
+      "mandatory_properties": [
+        {
+          "property": "timeout",
+          "requirement": "All external calls SHALL define timeouts",
+          "type": "number",
+          "constraint": ">0 and <=30000",
+          "units": "milliseconds"
+        },
+        {
+          "property": "retry_policy",
+          "requirement": "Retry logic SHALL be bounded and explicit",
+          "constraints": {
+            "max_attempts": "<=5",
+            "backoff_type": ["exponential", "linear", "fixed"],
+            "max_backoff_ms": "<=60000"
+          }
+        },
+        {
+          "property": "circuit_breaker",
+          "requirement": "High-volume external dependencies SHOULD implement circuit breakers",
+          "parameters": {
+            "failure_threshold": "configurable",
+            "timeout": "configurable",
+            "reset_timeout": "configurable"
+          }
+        },
+        {
+          "property": "graceful_degradation",
+          "requirement": "Failure modes SHALL be predictable",
+          "notes": "Unhandled error is not an acceptable system state"
+        }
+      ]
+    },
+
+    "O4_performance": {
+      "name": "Performance & Resource Control",
+      "scope": "all resource-intensive operations",
+      "mandatory_constraints": [
+        {
+          "constraint": "resource_isolation",
+          "rule": "Resource-heavy operations SHALL be isolated",
+          "examples": ["batch processing", "large file operations", "complex computations"]
+        },
+        {
+          "constraint": "explicit_caching",
+          "rule": "Caching SHALL be explicit and invalidation-defined",
+          "forbidden": "implicit caching without invalidation strategy"
+        },
+        {
+          "constraint": "bounded_operations",
+          "rule": "No unbounded loops or recursive calls",
+          "enforcement": "All loops must have explicit termination condition",
+          "notes": "Performance bugs become availability bugs at scale"
+        },
+        {
+          "constraint": "concurrency_limits",
+          "rule": "Concurrent operations SHALL have explicit limits"
+        },
+        {
+          "constraint": "memory_budgets",
+          "rule": "Large allocations SHALL be bounded and justified"
+        }
+      ]
+    },
+
+    "O5_observability": {
+      "name": "Observability",
+      "scope": "all critical paths and error conditions",
+      "mandatory_requirements": [
+        {
+          "requirement": "structured_logging",
+          "rule": "All critical paths SHALL emit structured logs",
+          "format": "machine-parseable (JSON recommended)",
+          "minimum_fields": ["timestamp", "level", "message", "context"]
+        },
+        {
+          "requirement": "error_detectability",
+          "rule": "Errors SHALL be machine-detectable",
+          "implementation": "structured error objects, not string messages"
+        },
+        {
+          "requirement": "business_metrics",
+          "rule": "Metrics SHALL align with business events",
+          "examples": ["user_action_completed", "transaction_processed", "api_call_made"]
+        },
+        {
+          "requirement": "tracing",
+          "rule": "Distributed operations SHOULD include trace IDs",
+          "propagation": "across service boundaries"
+        }
+      ],
+      "notes": "If you cannot observe it, AI cannot safely optimize it"
+    },
+
+    "O6_configuration": {
+      "name": "Configuration & Environment",
+      "scope": "all environment-dependent behavior",
+      "mandatory_rules": [
+        {
+          "rule": "no_environment_logic_in_domain",
+          "constraint": "No environment-specific logic in R1 or R2",
+          "allowed_location": "R4_infrastructure only"
+        },
+        {
+          "rule": "no_hardcoded_secrets",
+          "constraint": "Secrets SHALL NOT be hard-coded",
+          "enforcement": "blocking",
+          "detection": "scan for patterns like API keys, passwords, tokens"
+        },
+        {
+          "rule": "external_configuration",
+          "constraint": "Configuration SHALL be externally injectable",
+          "methods": ["environment variables", "config files", "external config service"]
+        },
+        {
+          "rule": "feature_flags",
+          "recommendation": "Use feature flags for gradual rollouts",
+          "location": "R4_execution"
+        }
+      ],
+      "notes": "Environment coupling is a hidden dependency dimension"
+    },
+
+    "O7_data_safety": {
+      "name": "Data Safety & Lifecycle",
+      "scope": "all data operations",
+      "mandatory_requirements": [
+        {
+          "requirement": "input_validation",
+          "rule": "All external inputs SHALL be validated",
+          "location": "R3_interface or R2_application",
+          "forbidden": "trusting external input without validation"
+        },
+        {
+          "requirement": "schema_versioning",
+          "rule": "Schema changes SHALL be versioned",
+          "applies_to": ["database schemas", "API contracts", "message formats"]
+        },
+        {
+          "requirement": "intentional_deletion",
+          "rule": "Data deletion SHALL be intentional and auditable",
+          "forbidden": "cascading deletes without explicit approval"
+        },
+        {
+          "requirement": "backup_strategy",
+          "rule": "Critical data SHALL have backup and recovery plan",
+          "testing": "recovery procedures SHALL be tested"
+        },
+        {
+          "requirement": "retention_policy",
+          "rule": "Data retention SHALL be explicitly defined",
+          "compliance": "Consider regulatory requirements (GDPR, etc.)"
+        }
+      ],
+      "notes": "Data bugs are permanent bugs"
+    }
+  },
+
+  "cross_dimension_rules": [
+    "No operational concern may violate architectural invariants",
+    "Operational logic SHALL NOT leak into Domain logic (R1)",
+    "Execution (R4) MAY support operational enforcement only"
+  ],
+
+  "review_protocol": {
+    "for_each_change": [
+      {
+        "step": 1,
+        "action": "Identify affected operational dimensions"
+      },
+      {
+        "step": 2,
+        "action": "Verify architectural compliance (D1-D5)"
+      },
+      {
+        "step": 3,
+        "action": "Verify bounded behavior (no infinite loops, unbounded retries, etc.)"
+      },
+      {
+        "step": 4,
+        "action": "Verify failure handling (timeouts, circuit breakers, error propagation)"
+      },
+      {
+        "step": 5,
+        "action": "Halt on violation"
+      }
+    ],
+    "notes": "Most production outages are review failures, not code failures"
+  },
+
+  "ai_instructions": {
+    "before_external_calls": [
+      "Add timeout parameter",
+      "Wrap in rate limiter if user/client-triggered",
+      "Define retry policy with max attempts <=5",
+      "Add structured error handling"
+    ],
+    "before_data_operations": [
+      "Validate all inputs",
+      "Check schema version compatibility",
+      "Ensure deletion is explicit and logged"
+    ],
+    "before_resource_intensive_ops": [
+      "Define concurrency limits",
+      "Add execution timeout",
+      "Implement progress monitoring"
+    ],
+    "on_violation": "HALT and request architectural review"
+  }
+}