musubi-sdd 0.1.0

package/src/templates/shared/steering/tech.md

@@ -0,0 +1,537 @@
+# Technology Stack
+
+**Project**: {{PROJECT_NAME}}
+**Last Updated**: {{DATE}}
+**Version**: 1.0
+
+---
+
+## Overview
+
+This document defines the approved technology stack for {{PROJECT_NAME}}. All development MUST use these technologies unless explicitly approved via Phase -1 Gate (Article VIII: Anti-Abstraction).
+
+---
+
+## Primary Technologies
+
+### Programming Languages
+
+| Language | Version | Usage | Notes |
+|----------|---------|-------|-------|
+| {{PRIMARY_LANGUAGE}} | {{VERSION}} | Primary application language | [Notes] |
+| SQL | PostgreSQL 15+ | Database queries | Via Prisma ORM |
+| TypeScript | 5.0+ | Type definitions | Strict mode enabled |
+
+### Runtime Environment
+
+- **Node.js**: {{NODE_VERSION}}+ (LTS)
+- **Package Manager**: npm {{NPM_VERSION}}+ / pnpm {{PNPM_VERSION}}+
+
+---
+
+## Frontend Stack
+
+### Framework
+
+**Primary Framework**: {{FRONTEND_FRAMEWORK}}
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {{FRONTEND_FRAMEWORK}} | {{VERSION}} | [Purpose] |
+| React | 18+ | UI library (if using Next.js/Remix) |
+| TypeScript | 5.0+ | Type safety |
+
+### UI Components
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| {{UI_LIBRARY}} | {{VERSION}} | Component library |
+| Tailwind CSS | 3.0+ | Utility-first CSS |
+| shadcn/ui | Latest | Component primitives |
+
+### State Management
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| {{STATE_LIBRARY}} | {{VERSION}} | [Global state / Server state] |
+| React Context | Built-in | Local state |
+| React Query | 5.0+ | Server state (if applicable) |
+
+### Form Handling
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| React Hook Form | 7.0+ | Form management |
+| Zod | 3.0+ | Schema validation |
+
+---
+
+## Backend Stack
+
+### Framework
+
+**Primary Framework**: {{BACKEND_FRAMEWORK}}
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {{BACKEND_FRAMEWORK}} | {{VERSION}} | API server |
+| Express | 4.0+ | Web framework (if using Node.js) |
+| Next.js API Routes | 14+ | Serverless API (if using Next.js) |
+
+### API Technologies
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| REST | - | Primary API style |
+| GraphQL | (Optional) | Complex data fetching |
+| OpenAPI | 3.0+ | API specification |
+
+---
+
+## Database Stack
+
+### Primary Database
+
+**Database**: {{DATABASE}}
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {{DATABASE}} | {{VERSION}} | Primary data store |
+| Prisma | 5.0+ | ORM and migrations |
+
+### Database Schema
+
+```prisma
+// Example schema structure
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(uuid())
+  email     String   @unique
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+```
+
+### Caching Layer
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Redis | 7.0+ | Session storage, caching |
+| In-memory cache | - | Development only |
+
+---
+
+## Authentication & Authorization
+
+### Authentication
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {{AUTH_METHOD}} | {{VERSION}} | User authentication |
+| bcrypt | 5.0+ | Password hashing (cost factor 12) |
+| JWT | - | Session tokens |
+
+**Password Requirements**:
+- Hashing: bcrypt with cost factor 12 (Article III: Security)
+- Minimum length: 12 characters
+- Complexity: Uppercase, lowercase, number, special char
+
+### Authorization
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| RBAC | - | Role-Based Access Control |
+| CASL | 6.0+ | Authorization library (optional) |
+
+---
+
+## Testing Stack
+
+### Test Frameworks
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {{TEST_FRAMEWORK}} | {{VERSION}} | Unit testing |
+| Jest | 29+ | Test runner (if using JavaScript/TypeScript) |
+| Vitest | 1.0+ | Fast test runner (alternative to Jest) |
+
+### Testing Libraries
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| React Testing Library | 14+ | Component testing |
+| Supertest | 6.0+ | API testing |
+| Playwright | 1.40+ | E2E testing |
+| Testing Library | Latest | DOM testing utilities |
+
+### Test Databases
+
+- **Integration Tests**: Real PostgreSQL (Docker container)
+- **Unit Tests**: Mocked repository layer
+- **E2E Tests**: Dedicated test database
+
+**Docker Compose** for test services:
+```yaml
+services:
+  test-db:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_PASSWORD: test
+      POSTGRES_DB: test
+    ports:
+      - "5432:5432"
+
+  test-redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+```
+
+**Constitutional Compliance (Article IX)**:
+- Integration tests MUST use real database
+- Integration tests MUST use real cache
+- Mocks only for external APIs without test environments
+
+---
+
+## Build & Development Tools
+
+### Build Tools
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| {{BUILD_TOOL}} | {{VERSION}} | Build system |
+| esbuild | Latest | Fast bundler |
+| Turbo | Latest | Monorepo build system |
+
+### Code Quality
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| ESLint | 8.0+ | JavaScript/TypeScript linting |
+| Prettier | 3.0+ | Code formatting |
+| TypeScript | 5.0+ | Type checking |
+| Husky | 8.0+ | Git hooks |
+| lint-staged | 14.0+ | Pre-commit linting |
+
+**ESLint Configuration**:
+```json
+{
+  "extends": [
+    "next/core-web-vitals",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "rules": {
+    "@typescript-eslint/no-unused-vars": "error",
+    "@typescript-eslint/no-explicit-any": "warn"
+  }
+}
+```
+
+---
+
+## CI/CD Stack
+
+### CI/CD Platform
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {{CI_CD_PLATFORM}} | - | Continuous Integration/Deployment |
+| GitHub Actions | - | CI/CD workflows |
+| GitLab CI | - | Alternative CI/CD |
+
+### Deployment
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Docker | 24.0+ | Containerization |
+| Docker Compose | 2.0+ | Multi-container apps (dev) |
+| Kubernetes | 1.28+ | Container orchestration (prod) |
+
+---
+
+## Cloud Infrastructure
+
+### Cloud Provider
+
+**Primary Provider**: {{CLOUD_PROVIDER}}
+
+| Service | Purpose |
+|---------|---------|
+| {{COMPUTE_SERVICE}} | Application hosting |
+| {{DATABASE_SERVICE}} | Managed database |
+| {{STORAGE_SERVICE}} | Object storage |
+| {{CACHE_SERVICE}} | Managed Redis |
+
+### Infrastructure as Code
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {{IAC_TOOL}} | {{VERSION}} | Infrastructure provisioning |
+| Terraform | 1.6+ | Cloud infrastructure |
+| Bicep | Latest | Azure infrastructure |
+
+---
+
+## Monitoring & Observability
+
+### Logging
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {{LOGGING_TOOL}} | {{VERSION}} | Log aggregation |
+| Winston | 3.0+ | Application logging (Node.js) |
+| Pino | 8.0+ | Fast logging (alternative) |
+
+**Log Format**: JSON
+
+```typescript
+// Example log entry
+{
+  "timestamp": "2025-11-16T10:00:00Z",
+  "level": "info",
+  "message": "User logged in",
+  "context": {
+    "userId": "uuid",
+    "ip": "192.168.1.1"
+  },
+  "traceId": "trace-id"
+}
+```
+
+### Monitoring
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {{MONITORING_TOOL}} | {{VERSION}} | Application monitoring |
+| Prometheus | 2.0+ | Metrics collection |
+| Grafana | 10.0+ | Metrics visualization |
+
+### Tracing
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {{TRACING_TOOL}} | {{VERSION}} | Distributed tracing |
+| OpenTelemetry | Latest | Tracing standard |
+| Jaeger | 1.50+ | Tracing backend |
+
+### Error Tracking
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Sentry | Latest | Error tracking and reporting |
+
+---
+
+## Documentation Tools
+
+### API Documentation
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| OpenAPI/Swagger | 3.0+ | REST API documentation |
+| GraphQL Playground | - | GraphQL API explorer |
+| Postman | Latest | API testing and docs |
+
+### Code Documentation
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| TSDoc | - | TypeScript documentation |
+| JSDoc | - | JavaScript documentation |
+| Storybook | 7.0+ | Component documentation |
+
+---
+
+## Development Tools
+
+### Code Editors
+
+- **Recommended**: Visual Studio Code
+- **Extensions**:
+  - ESLint
+  - Prettier
+  - TypeScript
+  - Prisma
+  - Tailwind CSS IntelliSense
+
+### Database Tools
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Prisma Studio | Built-in | Database GUI |
+| pgAdmin | 4.0+ | PostgreSQL admin |
+| TablePlus | Latest | Multi-database client |
+
+### API Testing
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Postman | Latest | API testing |
+| Insomnia | Latest | REST/GraphQL client |
+| curl | - | Command-line API testing |
+
+---
+
+## Security Tools
+
+### Security Scanning
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| npm audit | Built-in | Dependency vulnerability scanning |
+| Snyk | Latest | Continuous security monitoring |
+| OWASP ZAP | Latest | Security testing |
+
+### Secrets Management
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| {{SECRETS_TOOL}} | {{VERSION}} | Secrets management |
+| .env files | - | Local development secrets |
+| AWS Secrets Manager | - | Production secrets (AWS) |
+| Azure Key Vault | - | Production secrets (Azure) |
+
+---
+
+## Package Management
+
+### Dependency Management
+
+```json
+// package.json structure
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "test": "jest",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "dependencies": {
+    // Production dependencies
+  },
+  "devDependencies": {
+    // Development dependencies
+  }
+}
+```
+
+### Version Pinning
+
+- **Exact Versions**: Critical dependencies (database drivers, auth libraries)
+- **Caret Ranges**: UI libraries, utilities (`^1.2.3`)
+- **Lock Files**: Commit `package-lock.json` / `pnpm-lock.yaml`
+
+---
+
+## Framework-Specific Configurations
+
+### {{PRIMARY_FRAMEWORK}} Configuration
+
+[Include framework-specific configuration details]
+
+**Example for Next.js**:
+```typescript
+// next.config.js
+const nextConfig = {
+  reactStrictMode: true,
+  typescript: {
+    ignoreBuildErrors: false
+  },
+  eslint: {
+    ignoreDuringBuilds: false
+  },
+  experimental: {
+    serverActions: true
+  }
+};
+
+export default nextConfig;
+```
+
+---
+
+## Anti-Abstraction Policy (Article VIII)
+
+**CRITICAL**: Use framework APIs directly. Do NOT create custom abstraction layers.
+
+### ✅ Allowed
+
+```typescript
+// Use Prisma directly
+const user = await prisma.user.findUnique({ where: { id } });
+
+// Use bcrypt directly
+const hash = await bcrypt.hash(password, 12);
+
+// Use Next.js API routes directly
+export async function POST(request: Request) { ... }
+```
+
+### ❌ Prohibited (Without Phase -1 Gate Approval)
+
+```typescript
+// ❌ Custom database wrapper
+class MyDatabase {
+  async find(id: string) { ... }  // Wrapping Prisma
+}
+
+// ❌ Custom HTTP client
+class MyHttpClient {
+  async get(url: string) { ... }  // Wrapping fetch
+}
+```
+
+**Exception**: Multi-framework support or justified architectural need requires Phase -1 Gate approval with:
+1. Multi-framework justification
+2. Team expertise analysis
+3. Migration path documentation
+4. Approval from @system-architect + @software-developer
+
+---
+
+## Technology Selection Criteria
+
+When evaluating new technologies:
+
+1. **Community Support**: Active maintenance, large community
+2. **Documentation**: Comprehensive, up-to-date
+3. **Type Safety**: TypeScript support preferred
+4. **Performance**: Benchmarked performance metrics
+5. **Security**: Regular security updates
+6. **License**: Compatible with project (MIT, Apache 2.0 preferred)
+7. **Team Expertise**: Team familiarity with technology
+8. **Constitutional Alignment**: Supports Library-First, Test-First principles
+
+---
+
+## Deprecated Technologies
+
+| Technology | Deprecated Date | Replacement | Migration Deadline |
+|------------|----------------|-------------|-------------------|
+| [Old Tech] | [Date] | [New Tech] | [Date] |
+
+---
+
+## Changelog
+
+### Version 1.1 (Planned)
+- [Planned technology updates]
+
+---
+
+**Last Updated**: {{DATE}}
+**Maintained By**: {{MAINTAINER}}