ctxora 6.2.2 → 6.3.0

package/src/harness_context/skills/ecc/delivery-gate/hooks/quality-gate.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""
+Stop hook: quality gate with delivery check.
+Detects incomplete work, stale learning logs, and low disk space.
+Blocks Claude from stopping when a complex task completed without learning capture.
+
+Install: cp this file to ~/.claude/scripts/quality-gate.py
+Configure: Add to settings.json hooks.Stop
+"""
+from __future__ import annotations
+
+import sys
+import os
+import re
+import json
+import datetime
+import shutil
+import logging
+from typing import Optional
+
+# ---- Configuration ----
+RATIONALIZE = [
+    r'(?:this|that)\s+is\s+a\s+pre[- ]existing\s+(?:issue|bug)\b(?!\s+(?:that|which|and))',
+    r'skipping\s+(?:tests?|lint|coverage|type[- ]check)\s+for\s+now',
+    r'(?:tests?|coverage)\s+(?:are|is)\s+(?:failing|broken)\s+but\s+(?:I|we)\s+(?:\'ll|can|will)\s+(?:fix|address|resolve|handle)',
+    r'(?:not\s+addressing|won\'t\s+fix|leaving)\s+the\s+(?:failing|broken)\s+(?:tests?|builds?|integration\s+tests?)',
+]
+
+LIBS = {
+    'ratings-tracker': 'ratings-tracker.md',
+    'decisions-log': 'decisions/log.md',
+    'growth-log': 'growth-log/',
+    'output-index': 'output-index.md',
+    'tooling-capabilities': 'tooling_capabilities.md',
+}
+
+MIN_CHARS = 40
+COMPLEX_THRESHOLD = 3
+DISK_REMIND_GB = 50
+DISK_WARN_GB = 30
+DISK_CRIT_GB = 15
+# ---- End Configuration ----
+
+logging.basicConfig(
+    stream=sys.stderr,
+    format='%(levelname)s: %(message)s',
+    level=logging.INFO,
+)
+log = logging.getLogger('quality-gate')
+
+
+def get_project_memory_dir() -> Optional[str]:
+    """Find the current project's memory directory.
+
+    Returns None if no memory directory exists for this project.
+    Does NOT fall back to other projects (privacy boundary)."""
+    cwd = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+    safe = cwd.replace(':', '-').replace('\\', '-').replace('/', '-')
+    mem = os.path.expanduser(f'~/.claude/projects/{safe}/memory')
+    log.info('Looking for memory dir: cwd=%s -> %s', cwd, mem)
+    if os.path.isdir(mem):
+        return mem
+    return None
+
+
+def check_disk() -> Optional[int]:
+    """Check free space on the disk containing the home directory.
+
+    Works cross-platform: macOS, Linux, Windows.
+    Returns free GB, or None if the home directory is unavailable."""
+    try:
+        home = os.path.expanduser('~')
+        free_gb = shutil.disk_usage(home).free // (2**30)
+        return free_gb
+    except (FileNotFoundError, PermissionError, OSError):
+        log.warning('cannot check disk space (home dir inaccessible)')
+        return None
+
+
+def check_stale_libs(mem_dir: str) -> list[str]:
+    """Return list of library names not updated today.
+
+    Per-file OSError handling: individual unreadable files are skipped,
+    but the scan continues for remaining libraries."""
+    today = datetime.date.today()
+    stale: list[str] = []
+    for name, path in LIBS.items():
+        full = os.path.join(mem_dir, path)
+        try:
+            if os.path.isdir(full):
+                has_today = False
+                for dirpath, _dirnames, filenames in os.walk(full):
+                    for f in filenames:
+                        fp = os.path.join(dirpath, f)
+                        try:
+                            mt = datetime.datetime.fromtimestamp(os.path.getmtime(fp)).date()
+                            if mt == today:
+                                has_today = True
+                                break
+                        except OSError:
+                            continue
+                    if has_today:
+                        break
+                if not has_today:
+                    stale.append(name)
+            elif os.path.exists(full):
+                try:
+                    mt = datetime.datetime.fromtimestamp(os.path.getmtime(full)).date()
+                    if mt != today:
+                        stale.append(name)
+                except OSError:
+                    stale.append(name)
+            else:
+                stale.append(name)
+        except OSError as e:
+            log.warning('cannot access lib %s: %s', name, e)
+            stale.append(name)
+    return stale
+
+
+def count_edits(text: str) -> int:
+    """Count Edit/Write tool invocations in the full transcript.
+
+    Matches structured tool-call JSON patterns to avoid false-positives
+    from ordinary English prose. Scans entire transcript."""
+    return len(re.findall(r'"name":\s*"(?:Edit|Write)"', text))
+
+
+def main() -> None:
+    raw = sys.stdin.read()
+    # Stop hooks write feedback to stderr, not stdout.
+    # Claude Code reads stderr as the hook's response message.
+    # Do NOT echo raw JSON to stdout — it would overwrite the blocking reason.
+
+    # Resolve transcript: Stop hooks may receive raw text OR JSON with transcript_path.
+    transcript = raw
+    try:
+        payload = json.loads(raw)
+        if isinstance(payload, dict) and 'transcript_path' in payload:
+            tp = os.path.expanduser(payload['transcript_path'])
+            if os.path.exists(tp):
+                with open(tp, 'r', encoding='utf-8') as f:
+                    transcript = f.read()
+            else:
+                log.warning('transcript_path %s not found, falling back to raw stdin', tp)
+    except (json.JSONDecodeError, TypeError, OSError):
+        pass
+
+    # 1. Disk check — three-level: remind / warn / block
+    disk_free = check_disk()
+    if disk_free is not None:
+        if disk_free < DISK_CRIT_GB:
+            log.warning('Blocked: disk space at %dGB (<%dGB). Free space before continuing.',
+                        disk_free, DISK_CRIT_GB)
+            sys.exit(2)
+        if disk_free < DISK_WARN_GB:
+            log.warning('WARN: disk space at %dGB (<%dGB)', disk_free, DISK_WARN_GB)
+        elif disk_free < DISK_REMIND_GB:
+            log.info('Reminder: disk space at %dGB (<%dGB)', disk_free, DISK_REMIND_GB)
+
+    # 2. Short session — skip remaining checks
+    if len(transcript) < MIN_CHARS:
+        sys.exit(0)
+
+    tail = transcript[-8000:]
+
+    # 3. Rationalization pattern detection
+    hits = []
+    for p in RATIONALIZE:
+        m = re.search(p, tail, re.IGNORECASE)
+        if m:
+            hits.append(m.group(0)[:80])
+    if hits:
+        log.warning('quality-gate: rationalization detected — %s', hits)
+
+    # 4. Learning capture check
+    mem_dir = get_project_memory_dir()
+    edit_count = count_edits(transcript)
+    is_complex = edit_count >= COMPLEX_THRESHOLD
+
+    if mem_dir:
+        stale = check_stale_libs(mem_dir)
+    else:
+        # No memory dir — setup incomplete.
+        # Warn but DO NOT block: blocking here deadlocks new users
+        # who haven't created the memory directory yet.
+        if is_complex:
+            log.warning('No project memory directory found — cannot verify learning capture.')
+            log.warning('Set up memory/ per delivery-gate SKILL.md to enable enforcement.')
+        stale = []
+
+    parts = []
+    if is_complex:
+        status_icons = ['X' if s in stale else 'O' for s in LIBS]
+        parts.append(
+            f'\n  Complex task ({edit_count} edits). '
+            f'Check: [{"][".join(f"{k}:{v}" for k,v in zip(LIBS.keys(), status_icons))}]'
+        )
+    if stale:
+        parts.append(f'  Stale ({len(stale)}): {", ".join(stale)}')
+
+    if parts:
+        log.warning('\n'.join(parts))
+
+    # 5. Block if complex task completed without learning capture
+    if is_complex:
+        if len(stale) >= 3:
+            log.warning('Blocked: complex task but >=3 learning libs stale.')
+            log.warning(f'Stale: {", ".join(stale)}. Update before stopping.')
+            sys.exit(2)
+        if 'growth-log' in stale:
+            log.warning('Blocked: code changes made but no growth-log update.')
+            log.warning('Write growth-log before stopping (even if "no new learnings").')
+            sys.exit(2)
+
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/src/harness_context/skills/ecc/deployment-patterns/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/harness_context/skills/ecc/deployment-patterns/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: deployment-patterns
+description: Deployment workflows, CI/CD pipeline patterns, Docker containerization, health checks, rollback strategies, and production readiness checklists for web applications. Use when setting up CI/CD, containerizing an app, or checking production readiness before a release.
+metadata:
+  origin: ECC
+---
+
+# Deployment Patterns
+
+Production deployment workflows and CI/CD best practices.
+
+## When to Activate
+
+- Setting up CI/CD pipelines
+- Dockerizing an application
+- Planning deployment strategy (blue-green, canary, rolling)
+- Implementing health checks and readiness probes
+- Preparing for a production release
+- Configuring environment-specific settings
+
+## Deployment Strategies
+
+### Rolling Deployment (Default)
+
+Replace instances gradually — old and new versions run simultaneously during rollout.
+
+```
+Instance 1: v1 → v2  (update first)
+Instance 2: v1        (still running v1)
+Instance 3: v1        (still running v1)
+
+Instance 1: v2
+Instance 2: v1 → v2  (update second)
+Instance 3: v1
+
+Instance 1: v2
+Instance 2: v2
+Instance 3: v1 → v2  (update last)
+```
+
+**Pros:** Zero downtime, gradual rollout
+**Cons:** Two versions run simultaneously — requires backward-compatible changes
+**Use when:** Standard deployments, backward-compatible changes
+
+### Blue-Green Deployment
+
+Run two identical environments. Switch traffic atomically.
+
+```
+Blue  (v1) ← traffic
+Green (v2)   idle, running new version
+
+# After verification:
+Blue  (v1)   idle (becomes standby)
+Green (v2) ← traffic
+```
+
+**Pros:** Instant rollback (switch back to blue), clean cutover
+**Cons:** Requires 2x infrastructure during deployment
+**Use when:** Critical services, zero-tolerance for issues
+
+### Canary Deployment
+
+Route a small percentage of traffic to the new version first.
+
+```
+v1: 95% of traffic
+v2:  5% of traffic  (canary)
+
+# If metrics look good:
+v1: 50% of traffic
+v2: 50% of traffic
+
+# Final:
+v2: 100% of traffic
+```
+
+**Pros:** Catches issues with real traffic before full rollout
+**Cons:** Requires traffic splitting infrastructure, monitoring
+**Use when:** High-traffic services, risky changes, feature flags
+
+## Docker
+
+### Multi-Stage Dockerfile (Node.js)
+
+```dockerfile
+# Stage 1: Install dependencies
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --production=false
+
+# Stage 2: Build
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+RUN npm prune --production
+
+# Stage 3: Production image
+FROM node:22-alpine AS runner
+WORKDIR /app
+
+RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
+USER appuser
+
+COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
+COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
+COPY --from=builder --chown=appuser:appgroup /app/package.json ./
+
+ENV NODE_ENV=production
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
+CMD ["node", "dist/server.js"]
+```
+
+### Multi-Stage Dockerfile (Go)
+
+```dockerfile
+FROM golang:1.22-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server
+
+FROM alpine:3.19 AS runner
+RUN apk --no-cache add ca-certificates
+RUN adduser -D -u 1001 appuser
+USER appuser
+
+COPY --from=builder /server /server
+
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:8080/health || exit 1
+CMD ["/server"]
+```
+
+### Multi-Stage Dockerfile (Python/Django)
+
+```dockerfile
+FROM python:3.12-slim AS builder
+WORKDIR /app
+RUN pip install --no-cache-dir uv
+COPY requirements.txt .
+RUN uv pip install --system --no-cache -r requirements.txt
+
+FROM python:3.12-slim AS runner
+WORKDIR /app
+
+RUN useradd -r -u 1001 appuser
+USER appuser
+
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+COPY . .
+
+ENV PYTHONUNBUFFERED=1
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/')" || exit 1
+CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "4"]
+```
+
+### Docker Best Practices
+
+```
+# GOOD practices
+- Use specific version tags (node:22-alpine, not node:latest)
+- Multi-stage builds to minimize image size
+- Run as non-root user
+- Copy dependency files first (layer caching)
+- Use .dockerignore to exclude node_modules, .git, tests
+- Add HEALTHCHECK instruction
+- Set resource limits in docker-compose or k8s
+
+# BAD practices
+- Running as root
+- Using :latest tags
+- Copying entire repo in one COPY layer
+- Installing dev dependencies in production image
+- Storing secrets in image (use env vars or secrets manager)
+```
+
+## CI/CD Pipeline
+
+### GitHub Actions (Standard Pipeline)
+
+```yaml
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test -- --coverage
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage
+          path: coverage/
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v5
+        with:
+          push: true
+          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    environment: production
+    steps:
+      - name: Deploy to production
+        run: |
+          # Platform-specific deployment command
+          # Railway: railway up
+          # Vercel: vercel --prod
+          # K8s: kubectl set image deployment/app app=ghcr.io/${{ github.repository }}:${{ github.sha }}
+          echo "Deploying ${{ github.sha }}"
+```
+
+### Pipeline Stages
+
+```
+PR opened:
+  lint → typecheck → unit tests → integration tests → preview deploy
+
+Merged to main:
+  lint → typecheck → unit tests → integration tests → build image → deploy staging → smoke tests → deploy production
+```
+
+## Health Checks
+
+### Health Check Endpoint
+
+```typescript
+// Simple health check
+app.get("/health", (req, res) => {
+  res.status(200).json({ status: "ok" });
+});
+
+// Detailed health check (for internal monitoring)
+app.get("/health/detailed", async (req, res) => {
+  const checks = {
+    database: await checkDatabase(),
+    redis: await checkRedis(),
+    externalApi: await checkExternalApi(),
+  };
+
+  const allHealthy = Object.values(checks).every(c => c.status === "ok");
+
+  res.status(allHealthy ? 200 : 503).json({
+    status: allHealthy ? "ok" : "degraded",
+    timestamp: new Date().toISOString(),
+    version: process.env.APP_VERSION || "unknown",
+    uptime: process.uptime(),
+    checks,
+  });
+});
+
+async function checkDatabase(): Promise<HealthCheck> {
+  try {
+    await db.query("SELECT 1");
+    return { status: "ok", latency_ms: 2 };
+  } catch (err) {
+    return { status: "error", message: "Database unreachable" };
+  }
+}
+```
+
+### Kubernetes Probes
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /health
+    port: 3000
+  initialDelaySeconds: 10
+  periodSeconds: 30
+  failureThreshold: 3
+
+readinessProbe:
+  httpGet:
+    path: /health
+    port: 3000
+  initialDelaySeconds: 5
+  periodSeconds: 10
+  failureThreshold: 2
+
+startupProbe:
+  httpGet:
+    path: /health
+    port: 3000
+  initialDelaySeconds: 0
+  periodSeconds: 5
+  failureThreshold: 30    # 30 * 5s = 150s max startup time
+```
+
+## Environment Configuration
+
+### Twelve-Factor App Pattern
+
+```bash
+# All config via environment variables — never in code
+DATABASE_URL=postgres://user:pass@host:5432/db
+REDIS_URL=redis://host:6379/0
+API_KEY=${API_KEY}           # injected by secrets manager
+LOG_LEVEL=info
+PORT=3000
+
+# Environment-specific behavior
+NODE_ENV=production          # or staging, development
+APP_ENV=production           # explicit app environment
+```
+
+### Configuration Validation
+
+```typescript
+import { z } from "zod";
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(["development", "staging", "production"]),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+});
+
+// Validate at startup — fail fast if config is wrong
+export const env = envSchema.parse(process.env);
+```
+
+## Rollback Strategy
+
+### Instant Rollback
+
+```bash
+# Docker/Kubernetes: point to previous image
+kubectl rollout undo deployment/app
+
+# Vercel: promote previous deployment
+vercel rollback
+
+# Railway: redeploy previous commit
+railway up --commit <previous-sha>
+
+# Database: rollback migration (if reversible)
+npx prisma migrate resolve --rolled-back <migration-name>
+```
+
+### Rollback Checklist
+
+- [ ] Previous image/artifact is available and tagged
+- [ ] Database migrations are backward-compatible (no destructive changes)
+- [ ] Feature flags can disable new features without deploy
+- [ ] Monitoring alerts configured for error rate spikes
+- [ ] Rollback tested in staging before production release
+
+## Production Readiness Checklist
+
+Before any production deployment:
+
+### Application
+- [ ] All tests pass (unit, integration, E2E)
+- [ ] No hardcoded secrets in code or config files
+- [ ] Error handling covers all edge cases
+- [ ] Logging is structured (JSON) and does not contain PII
+- [ ] Health check endpoint returns meaningful status
+
+### Infrastructure
+- [ ] Docker image builds reproducibly (pinned versions)
+- [ ] Environment variables documented and validated at startup
+- [ ] Resource limits set (CPU, memory)
+- [ ] Horizontal scaling configured (min/max instances)
+- [ ] SSL/TLS enabled on all endpoints
+
+### Monitoring
+- [ ] Application metrics exported (request rate, latency, errors)
+- [ ] Alerts configured for error rate > threshold
+- [ ] Log aggregation set up (structured logs, searchable)
+- [ ] Uptime monitoring on health endpoint
+
+### Security
+- [ ] Dependencies scanned for CVEs
+- [ ] CORS configured for allowed origins only
+- [ ] Rate limiting enabled on public endpoints
+- [ ] Authentication and authorization verified
+- [ ] Security headers set (CSP, HSTS, X-Frame-Options)
+
+### Operations
+- [ ] Rollback plan documented and tested
+- [ ] Database migration tested against production-sized data
+- [ ] Runbook for common failure scenarios
+- [ ] On-call rotation and escalation path defined

package/src/harness_context/skills/ecc/design-system/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.