@a-company/paradigm 1.5.0

package/templates/paradigm/specs/history.md

@@ -0,0 +1,339 @@
+# History System Specification
+
+> **Paradigm v1.1** | Implementation log, validation, fragility tracking
+
+## Overview
+
+The History system captures the **temporal and empirical dimension** of development - what was implemented, what worked, what was rolled back, and how stable different areas are over time. It's the project's memory, indexed by Paradigm symbols.
+
+## Purpose
+
+- **Track what changed** - append-only log of implementations, validations, rollbacks
+- **Identify fragile areas** - symbols with frequent failures or rollbacks need extra care
+- **Detect co-change patterns** - symbols that often change together
+- **Guide AI agents** - check stability before modifying risky areas
+- **Enable post-mortems** - full history for any symbol
+
+## Storage Structure
+
+```
+.paradigm/history/
+├── log.jsonl           # Append-only implementation log
+├── index.yaml          # Pre-computed symbol index (regenerated)
+└── validation.yaml     # Validation config + summary
+```
+
+## Schema: log.jsonl
+
+Append-only, one JSON object per line. Never edit - only append.
+
+```jsonl
+{"id":"h0001","ts":"2026-02-02T10:00:00Z","type":"implement","symbols":["#checkout"],"author":{"type":"agent","id":"builder"},"commit":"abc123","intent":"feature","files":["src/checkout/page.tsx"],"description":"Added Apple Pay support"}
+{"id":"h0002","ts":"2026-02-02T10:30:00Z","type":"validate","ref":"h0001","symbols":[],"author":{"type":"agent","id":"tester"},"result":"pass","tests":{"passed":15,"failed":0}}
+{"id":"h0003","ts":"2026-02-03T09:00:00Z","type":"rollback","ref":"h0001","symbols":["#checkout"],"author":{"type":"human","id":"alice"},"reason":"Performance regression on mobile"}
+```
+
+### Entry Types
+
+| Type | Description |
+|------|-------------|
+| `implement` | New feature, bug fix, or change |
+| `validate` | Test results for an implementation |
+| `rollback` | Reverting a previous change |
+| `refactor` | Code restructuring without behavior change |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique ID (h0001, h0002, ...) |
+| `ts` | string | ISO timestamp |
+| `type` | string | Entry type (implement/validate/rollback/refactor) |
+| `symbols` | string[] | Affected Paradigm symbols |
+| `author` | object | `{type: "human"|"agent", id: string}` |
+| `commit` | string? | Git commit hash |
+| `intent` | string? | feature/fix/refactor/experimental/confirmed |
+| `files` | string[]? | Affected files |
+| `description` | string? | What was done |
+| `ref` | string? | Reference to related entry (for validate/rollback) |
+| `result` | string? | pass/fail/partial (for validate) |
+| `tests` | object? | `{passed, failed, skipped}` (for validate) |
+| `reason` | string? | Reason for rollback |
+
+## Schema: index.yaml
+
+Pre-computed from log.jsonl. Regenerate with `paradigm history reindex`.
+
+```yaml
+version: "1.0"
+generated: "2026-02-02T12:00:00Z"
+
+by_symbol:
+  "#checkout":
+    symbol: "#checkout"
+    total_changes: 45
+    last_modified: "2026-02-02T10:00:00Z"
+    stability_score: 0.87    # 0.0-1.0, higher is better
+    fragility: low           # low | medium | high | critical
+    recent:
+      - id: h0045
+        type: implement
+        description: "Added Apple Pay"
+        ts: "2026-02-02T10:00:00Z"
+      # ... last 5 entries
+    contributors:
+      human: ["alice", "bob"]
+      agent: ["builder", "fixer"]
+
+  "#search":
+    symbol: "#search"
+    total_changes: 23
+    last_modified: "2026-01-28T15:00:00Z"
+    stability_score: 0.62
+    fragility: high
+    recent: [...]
+    contributors:
+      human: ["carol"]
+      agent: ["builder"]
+
+co_changes:
+  - symbols: ["#checkout", "#payment-form"]
+    frequency: 15        # Changed together 15 times
+    correlation: 0.89    # 89% of #checkout changes include #payment-form
+
+  - symbols: ["#search", "#search-index"]
+    frequency: 12
+    correlation: 0.78
+
+fragile_symbols:
+  - symbol: "#search"
+    fragility: high
+    reason: "3 rollbacks in last 10 changes"
+
+  - symbol: "#legacy-api"
+    fragility: critical
+    reason: "Stability score 0.41, 5 failures in last month"
+```
+
+## Schema: validation.yaml
+
+```yaml
+version: "1.0"
+last_run: "2026-02-02T11:00:00Z"
+total_validations: 156
+pass_rate: 0.92
+
+by_symbol:
+  "#checkout":
+    symbol: "#checkout"
+    last_validated: "2026-02-02T10:30:00Z"
+    last_result: pass
+    pass_count: 45
+    fail_count: 3
+    coverage: 0.87
+
+  "#search":
+    symbol: "#search"
+    last_validated: "2026-01-28T16:00:00Z"
+    last_result: fail
+    pass_count: 18
+    fail_count: 5
+    coverage: 0.72
+```
+
+## Fragility Scoring
+
+Stability score is calculated from:
+
+```
+base = 1.0
+penalty_per_rollback = 0.20
+penalty_per_failure = 0.10
+normalized_changes = total_changes / 10
+
+stability = max(0, base - (rollbacks * 0.20 + failures * 0.10) / max(1, normalized_changes))
+```
+
+Fragility levels:
+
+| Score | Level | Meaning |
+|-------|-------|---------|
+| 0.85+ | low | Safe to modify |
+| 0.70-0.85 | medium | Moderate care needed |
+| 0.50-0.70 | high | Extra testing recommended |
+| <0.50 | critical | Consider deferring or extensive review |
+
+## MCP Resources
+
+| URI | Description |
+|-----|-------------|
+| `paradigm://history/symbol/{symbol}` | Full history for a symbol |
+| `paradigm://history/symbol/{symbol}/recent` | Last 5 changes only |
+| `paradigm://history/fragile` | List of fragile symbols |
+| `paradigm://history/cochanges/{symbol}` | Co-change patterns |
+| `paradigm://history/validation/summary` | Validation statistics |
+
+## MCP Tools
+
+### paradigm_history_context
+
+Get history before modifying symbols.
+
+```json
+{
+  "name": "paradigm_history_context",
+  "arguments": {
+    "symbols": ["#checkout", "#payment-form"]
+  }
+}
+```
+
+**Returns:** Summary, recent changes, contributors, co-change patterns for each symbol.
+
+### paradigm_history_record
+
+Record an implementation event.
+
+```json
+{
+  "name": "paradigm_history_record",
+  "arguments": {
+    "type": "implement",
+    "symbols": ["#checkout"],
+    "intent": "feature",
+    "description": "Added Apple Pay support",
+    "commit": "abc123",
+    "files": ["src/checkout/page.tsx"]
+  }
+}
+```
+
+### paradigm_history_validate
+
+Record test results.
+
+```json
+{
+  "name": "paradigm_history_validate",
+  "arguments": {
+    "implementation_id": "h0045",
+    "result": "pass",
+    "tests": {"passed": 15, "failed": 0}
+  }
+}
+```
+
+### paradigm_history_fragility
+
+Check fragility before modifying.
+
+```json
+{
+  "name": "paradigm_history_fragility",
+  "arguments": {
+    "symbols": ["#search", "#checkout"]
+  }
+}
+```
+
+**Returns:** Fragility levels, warnings, recommendations.
+
+## CLI Commands
+
+```bash
+# Show history overview
+paradigm history
+
+# Show history for a symbol
+paradigm history show #checkout
+
+# Initialize history directory
+paradigm history init
+
+# Show fragile symbols
+paradigm history fragile
+
+# Regenerate index from log
+paradigm history reindex
+
+# Record an implementation
+paradigm history record \
+  --type implement \
+  --symbols "#checkout" \
+  --description "Added Apple Pay" \
+  --intent feature
+
+# Record validation result
+paradigm history validate \
+  --result pass \
+  --ref h0045 \
+  --passed 15 \
+  --failed 0
+```
+
+## Git Hooks
+
+Automatic history capture via git hooks.
+
+```bash
+# Install hooks
+paradigm hooks install
+
+# Hooks installed:
+# - post-commit: Records implementation entries from commits
+# - pre-push: Reindexes history
+```
+
+Post-commit hook extracts:
+- Symbols from .purpose files in changed directories
+- Intent from commit message prefix (feat/fix/refactor)
+- Files changed
+- Commit hash and author
+
+## Agent Workflow
+
+Before modifying code, AI agents should:
+
+1. **Check fragility** for symbols they're modifying
+2. **Review recent history** - what changed, what broke
+3. **Note co-change patterns** - related symbols may need updates
+4. **After implementing**, record the change
+
+Example:
+
+```
+Agent: "I need to modify #search to add filters"
+
+1. Call paradigm_history_fragility(symbols: ["#search"])
+   → fragility: "high"
+   → reason: "3 rollbacks in last 10 changes"
+   → recommendation: "Add extra test coverage"
+
+2. Call paradigm_history_context(symbols: ["#search"])
+   → Recent: 2 rollbacks, 1 performance issue
+   → Co-changes: often changes with #search-index
+   → Contributors: carol (human), builder (agent)
+
+3. Implement with extra care, add comprehensive tests
+
+4. After commit, call paradigm_history_record(...)
+
+5. After tests pass, call paradigm_history_validate(...)
+```
+
+## Best Practices
+
+1. **Always record** - even failed attempts provide learning
+2. **Check fragility first** - before modifying unknown areas
+3. **Respect co-change patterns** - if A often changes with B, check B
+4. **Reindex periodically** - after batch operations
+5. **Review fragile symbols** - in sprint planning
+
+## Token Cost Optimization
+
+- Fragility check: ~50-80 tokens
+- Symbol history (recent only): ~100-150 tokens
+- Full history: ~200-400 tokens
+- Co-change patterns: ~50-100 tokens
+
+Pre-computed index.yaml avoids scanning full log.

package/templates/paradigm/specs/logger.md

@@ -0,0 +1,303 @@
+# Paradigm Logger Specification (v2)
+
+The Paradigm Logger creates a **shared language between code, developers, and AI agents** using Paradigm's symbol system v2. It replaces raw `console.log`/`print` statements with structured, filterable, symbol-typed logs.
+
+---
+
+## Core Principle
+
+**NEVER use raw logging. ALWAYS use the Paradigm logger.**
+
+```
+// BAD - Raw logging
+console.log('User logged in', userId);
+print(f"Query took {duration}ms")
+
+// GOOD - Paradigm logger (v2)
+log.component('#login-handler').info('User logged in', { userId });
+log.component('#database').debug('Query executed', { duration });
+```
+
+---
+
+## API Design (v2 - Language-Agnostic)
+
+### Logger Object
+
+```
+log.component('#symbol')  → SymbolLogger   // For #components (universal code units)
+log.gate('^symbol')       → SymbolLogger   // For ^gates (authorization)
+log.signal('!symbol')     → SymbolLogger   // For !signals (events)
+log.flow('$symbol')       → SymbolLogger   // For $flows (multi-step processes)
+log.aspect('~symbol')     → SymbolLogger   // For ~aspects (cross-cutting rules)
+log.raw('symbol')         → SymbolLogger   // For any symbol without prefix validation
+```
+
+### SymbolLogger Methods
+
+```
+.debug(message, data?)    // Verbose debugging info
+.info(message, data?)     // General information
+.warn(message, data?)     // Warning conditions
+.error(message, data?)    // Error conditions
+.start(message, data?)    → DurationTracker  // Start timed operation
+```
+
+### DurationTracker Methods
+
+```
+.success(message, data?)  // Operation succeeded (logs duration)
+.error(message, data?)    // Operation failed (logs duration)
+.end(level, message, data?)  // Custom level completion
+```
+
+---
+
+## Log Levels
+
+| Level | Priority | When to Use |
+|-------|----------|-------------|
+| `debug` | 0 | Internal state, cache hits, queries — verbose dev info |
+| `info` | 1 | Component entry/exit, successful operations |
+| `warn` | 2 | Denied access, retries, recoverable issues |
+| `error` | 3 | Exceptions, unrecoverable failures |
+
+**Default:** `debug` in development, `info` in production.
+
+---
+
+## Symbol Usage by Location (v2)
+
+In v2, all code units use `#component`. The tag system handles classification.
+
+| Directory Pattern | Symbol | Log Method |
+|-------------------|--------|------------|
+| `features/`, `routes/`, `api/` | `#` | `log.component()` |
+| `components/`, `lib/`, `utils/` | `#` | `log.component()` |
+| `services/`, `core/`, `drivers/` | `#` | `log.component()` |
+| `integrations/`, `external/`, `vendors/` | `#` | `log.component()` |
+| `stores/`, `state/`, `reducers/` | `#` | `log.component()` |
+| `config/`, `models/` | `#` | `log.component()` |
+| `middleware/`, `auth/`, `guards/`, `policies/` | `^` | `log.gate()` |
+| `events/`, `handlers/`, `listeners/`, `hooks/` | `!` | `log.signal()` |
+| `flows/`, `sagas/`, `workflows/`, `pipelines/` | `$` | `log.flow()` |
+| `aspects/`, `rules/`, `constraints/` | `~` | `log.aspect()` |
+
+---
+
+## Common Patterns
+
+### Component Entry/Exit
+
+```
+function login(email, password):
+    tracker = log.component('#login-handler').start('Starting login', { email })
+
+    try:
+        user = authenticate(email, password)
+        log.signal('!login-success').info('User authenticated', { userId: user.id })
+        tracker.success('Login completed', { userId: user.id })
+        return user
+    catch error:
+        log.signal('!login-failed').warn('Login failed', { email, error })
+        tracker.error('Login failed', { error })
+        throw error
+```
+
+### Gate Checks
+
+```
+function requireAuth(request):
+    log.gate('^authenticated').debug('Checking gate')
+
+    user = getUser(request)
+    if not user:
+        log.gate('^authenticated').warn('Access denied', { path: request.path })
+        return unauthorized()
+
+    log.gate('^authenticated').debug('Gate passed', { userId: user.id })
+    return next()
+```
+
+> **Note:** For authorization flows that need AI validation, use the **Portal Validator** instead.
+> See [Portal Validation Specification](./portal-validation.md) for structured decision logging.
+
+### Component Operations
+
+```
+function query(sql, params):
+    tracker = log.component('#database').start('Executing query')
+
+    try:
+        result = db.execute(sql, params)
+        tracker.success('Query completed', { rows: result.length })
+        return result
+    catch error:
+        tracker.error('Query failed', { error })
+        throw error
+```
+
+### Integration Components
+
+```
+function processPayment(amount, token):
+    tracker = log.component('#stripe-client').start('Processing payment', { amount })
+
+    try:
+        result = stripe.charges.create({ amount, source: token })
+        log.signal('!payment-completed').info('Payment processed', { chargeId: result.id })
+        tracker.success('Payment completed', { chargeId: result.id })
+        return result
+    catch error:
+        log.signal('!payment-failed').error('Payment failed', { error })
+        tracker.error('Payment failed', { error })
+        throw error
+```
+
+### Aspect Enforcement
+
+```
+function auditMiddleware(request, next):
+    log.aspect('~audit-required').debug('Audit middleware invoked', { path: request.path })
+
+    before = captureState()
+    result = next(request)
+    after = captureState()
+
+    log.aspect('~audit-required').info('Operation audited', {
+        path: request.path,
+        changes: diff(before, after)
+    })
+
+    return result
+```
+
+### State Components
+
+```
+function setAuthenticated(value):
+    log.component('#user-store').info('State changing', {
+        from: state.authenticated,
+        to: value
+    })
+    state.authenticated = value
+```
+
+---
+
+## Filtering
+
+### By Log Level
+
+```bash
+# Environment variable
+LOG_LEVEL=debug    # Show all
+LOG_LEVEL=info     # Show info, warn, error
+LOG_LEVEL=warn     # Show warn, error
+LOG_LEVEL=error    # Show errors only
+```
+
+### By Symbol Type
+
+```bash
+# Environment variable (comma-separated)
+PARADIGM_SYMBOLS=!          # Signals only — high-level overview
+PARADIGM_SYMBOLS=#,^,!      # Components, gates, signals — auth debugging
+PARADIGM_SYMBOLS=#          # Components only — infrastructure debugging
+PARADIGM_SYMBOLS=~          # Aspects only — rule enforcement debugging
+```
+
+### Common Filter Recipes
+
+| Use Case | Level | Symbols | What You See |
+|----------|-------|---------|--------------|
+| High-level overview | info | `!` | Just events/signals |
+| Auth debugging | debug | `#,^,!` | Components, gates, signals |
+| Infrastructure | debug | `#,!` | Components and signals |
+| Rule enforcement | debug | `~,!` | Aspects and signals |
+| Minimal | warn | (all) | Warnings and errors only |
+
+---
+
+## Output Formats
+
+### Development (Pretty)
+
+```
+16:42:15.123 #login-handler INFO  Starting login {"email":"user@example.com"}
+16:42:15.456 #database DEBUG Query executed {"table":"users","duration":"45ms"}
+16:42:15.789 !login-success INFO User authenticated {"userId":"abc123"}
+```
+
+### Production (JSON)
+
+```json
+{"timestamp":"2026-01-14T00:42:15.123Z","level":"info","symbol":"#login-handler","symbolType":"component","message":"Starting login","email":"user@example.com"}
+```
+
+---
+
+## Correlation IDs
+
+Track requests across multiple log statements:
+
+```
+correlationId = createCorrelationId()
+
+withCorrelation(correlationId, () => {
+    log.component('#checkout').info('Starting checkout')
+    log.component('#payment').info('Processing payment')
+    log.signal('!checkout-complete').info('Order placed')
+    // All logs include the same correlationId
+})
+```
+
+---
+
+## Implementation Checklist
+
+When implementing the Paradigm logger in a new language:
+
+- [ ] Symbol-typed methods: `log.component()`, `log.gate()`, `log.signal()`, `log.flow()`, `log.aspect()`
+- [ ] Log levels: debug, info, warn, error
+- [ ] Duration tracking: `.start()` → `.success()` / `.error()`
+- [ ] Structured data parameter on all methods
+- [ ] Level filtering via environment variable
+- [ ] Symbol filtering via environment variable
+- [ ] Pretty format for development
+- [ ] JSON format for production
+- [ ] Correlation ID support
+- [ ] Timestamp in output
+
+---
+
+## Portal Validation
+
+For authorization decisions that need to be validated by AI agents, use the **Portal Validator** alongside the standard logger. The Portal Validator emits structured decision logs:
+
+```
+┌─────────────────────────────────────────────────────────
+│ 🚪 PORTAL CHECK: ^subscription-required
+│ ├─ Requires: active subscription, trial not exceeded
+│ ├─ Context: { userId: "abc123", plan: "growth" }
+│ ├─ Decision: ✅ ALLOW
+│ └─ Reason: Subscription valid - growth plan active
+└─────────────────────────────────────────────────────────
+```
+
+Use cases:
+- **`log.gate()`** - General gate-related logging and debugging
+- **`portal.check()`** - Authorization decisions that need validation
+
+See [Portal Validation Specification](./portal-validation.md) for full details.
+
+---
+
+## Reference Implementations
+
+See working implementations in:
+- **TypeScript (Browser):** Pattern with CSS console styling
+- **TypeScript (Node.js):** Pattern with ANSI codes + AsyncLocalStorage
+- **Python:** Pattern with logging module
+- **Go:** Pattern with structured logging
+- **Rust:** Pattern with tracing crate