@ryuenn3123/agentic-senior-core 1.8.0

package/.agent-context/blueprints/ci-gitlab.md

@@ -0,0 +1,200 @@
+# Blueprint: GitLab CI/CD Pipeline
+
+> Same principles as GitHub Actions, adapted for GitLab's pipeline model.
+
+## Tech Stack
+
+| Layer | Tool |
+|-------|------|
+| CI/CD | GitLab CI/CD |
+| Config | `.gitlab-ci.yml` |
+| Runners | Shared runners or dedicated (Docker executor) |
+| Registry | GitLab Container Registry |
+| Caching | GitLab CI cache (per-branch, per-job) |
+
+## Pipeline Architecture
+
+```yaml
+stages:
+  - validate    # Lint + type check
+  - test        # Unit + integration tests
+  - security    # Dependency audit + SAST
+  - build       # Compile, bundle, containerize
+  - judge       # LLM-as-a-Judge checklist gate
+  - deploy      # Staging → Production
+```
+
+## Pipeline Template (`.gitlab-ci.yml`)
+
+```yaml
+default:
+  image: node:22-alpine
+  cache:
+    key:
+      files: [package-lock.json]
+    paths: [node_modules/]
+    policy: pull-push
+
+stages:
+  - validate
+  - test
+  - security
+  - build
+  - judge
+  - deploy
+
+# ─── VALIDATE ───────────────────────────────────────────
+lint:
+  stage: validate
+  script:
+    - npm ci --prefer-offline
+    - npm run lint
+    - npm run type-check
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+# ─── TEST ───────────────────────────────────────────────
+test:unit:
+  stage: test
+  script:
+    - npm ci --prefer-offline
+    - npm run test -- --coverage
+  coverage: '/All files\s*\|\s*(\d+\.?\d*)\s*\|/'
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage/cobertura-coverage.xml
+    paths: [coverage/]
+    expire_in: 7 days
+
+test:integration:
+  stage: test
+  services:
+    - postgres:16-alpine
+  variables:
+    POSTGRES_DB: test_db
+    POSTGRES_USER: test_user
+    POSTGRES_PASSWORD: test_pass
+    DATABASE_URL: "postgresql://test_user:test_pass@postgres:5432/test_db"
+  script:
+    - npm ci --prefer-offline
+    - npm run test:integration
+
+# ─── SECURITY ───────────────────────────────────────────
+audit:
+  stage: security
+  script:
+    - npm audit --audit-level=high
+  allow_failure: false
+
+sast:
+  stage: security
+  # GitLab's built-in SAST template
+include:
+  - template: Security/SAST.gitlab-ci.yml
+
+# ─── BUILD ──────────────────────────────────────────────
+build:
+  stage: build
+  script:
+    - npm ci --prefer-offline
+    - npm run build
+  artifacts:
+    paths: [dist/]
+    expire_in: 1 day
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+# ─── LLM JUDGE ──────────────────────────────────────────
+llm:judge:
+  stage: judge
+  image: node:22-alpine
+  variables:
+    OPENAI_API_KEY: $OPENAI_API_KEY
+    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
+    GEMINI_API_KEY: $GEMINI_API_KEY
+    # CI_MERGE_REQUEST_DIFF_BASE_SHA and CI_COMMIT_SHA are set automatically
+    # by GitLab for merge request pipelines — no manual configuration needed.
+  before_script:
+    - git fetch --unshallow || true  # Ensure full history for git diff
+  script:
+    - node scripts/llm-judge.mjs
+  artifacts:
+    when: always
+    paths:
+      - .agent-context/state/llm-judge-report.json
+    expire_in: 7 days
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+
+# ─── DEPLOY ─────────────────────────────────────────────
+deploy:staging:
+  stage: deploy
+  environment:
+    name: staging
+    url: https://staging.example.com
+  script:
+    - echo "Deploy to staging"
+    # Add your deployment commands
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+deploy:production:
+  stage: deploy
+  environment:
+    name: production
+    url: https://example.com
+  script:
+    - echo "Deploy to production"
+    # Add your deployment commands
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: manual  # Require manual approval
+  needs: [deploy:staging]
+```
+
+## Key Differences from GitHub Actions
+
+| Concern | GitHub Actions | GitLab CI |
+|---------|---------------|-----------|
+| Config file | `.github/workflows/*.yml` | `.gitlab-ci.yml` (single file) |
+| Jobs linkage | `needs:` | `stages:` (sequential) + `needs:` (DAG) |
+| Secrets | GitHub Secrets | CI/CD Variables (masked + protected) |
+| Caching | `actions/cache` | Built-in `cache:` directive |
+| Services | Docker Compose / service containers | `services:` directive |
+| Environments | Environment protection rules | Environment + `when: manual` |
+| Includes | Reusable workflows | `include:` with `template:` |
+
+## Security Rules
+
+1. **Protected variables** — mark secrets as Protected + Masked
+2. **Protected branches** — only deploy from protected branches
+3. **Include GitLab SAST/DAST** templates for automated scanning
+4. **Limit runner access** — use tags to route jobs to appropriate runners
+5. **Artifact expiration** — set `expire_in` on all artifacts
+6. **Limit LLM input scope** — send only merge diff + checklist context
+
+## Scaffolding Checklist
+
+- [ ] Create `.gitlab-ci.yml` with validate, test, security, build, deploy stages
+- [ ] Configure CI/CD variables for secrets (masked + protected)
+- [ ] Set up caching for package manager lockfile
+- [ ] Add coverage reporting with Cobertura format
+- [ ] Configure environments (staging, production) with manual approval
+- [ ] Include SAST template for security scanning
+- [ ] Set up merge request pipelines with `rules:`
+- [ ] Configure branch protection rules
+- [ ] Add `timeout` to long-running jobs
+- [ ] Use `needs:` for DAG optimization where possible
+- [ ] Add `llm:judge` stage that enforces `pr-checklist.md`
+
+## LLM Judge Annotation Contract
+
+For MR annotations and dashboards, parse either:
+
+- Log line: `JSON_REPORT: { ... }`
+- Artifact: `.agent-context/state/llm-judge-report.json`
+
+Severity values are normalized by the judge to: `critical`, `high`, `medium`, `low`.

package/.agent-context/blueprints/fastapi-service.md

@@ -0,0 +1,210 @@
+# Blueprint: FastAPI Service
+
+> Python backend API service using FastAPI, Pydantic v2, SQLAlchemy 2.0, and Alembic.
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | FastAPI |
+| Validation | Pydantic v2 |
+| ORM | SQLAlchemy 2.0 (async) |
+| Migration | Alembic |
+| Testing | pytest + pytest-asyncio + httpx |
+| Logging | structlog |
+| Linting | ruff (lint + format) |
+| Type checking | pyright (strict) |
+| Env config | pydantic-settings |
+
+---
+
+## Project Structure
+
+```
+project-name/
+├── src/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── config.py
+│   │
+│   ├── modules/
+│   │   └── user/
+│   │       ├── __init__.py
+│   │       ├── router.py
+│   │       ├── service.py
+│   │       ├── repository.py
+│   │       ├── schemas.py
+│   │       ├── models.py
+│   │       └── exceptions.py
+│   │
+│   └── shared/
+│       ├── __init__.py
+│       ├── database.py
+│       ├── errors.py
+│       ├── logger.py
+│       └── middleware.py
+│
+├── tests/
+│   ├── conftest.py
+│   ├── factories.py
+│   └── modules/
+│       └── user/
+│           └── test_user_service.py
+│
+├── alembic/
+│   ├── env.py
+│   └── versions/
+│
+├── pyproject.toml
+├── alembic.ini
+├── .env.example
+├── Dockerfile
+└── Makefile
+```
+
+---
+
+## File Patterns
+
+### config.py — Environment Validation
+```python
+from pydantic_settings import BaseSettings
+from pydantic import Field
+
+class Settings(BaseSettings):
+    database_url: str = Field(
+        description="PostgreSQL connection string"
+    )
+    jwt_secret: str = Field(min_length=32)
+    app_env: str = Field(default="development", pattern="^(development|staging|production)$")
+    cors_origins: list[str] = Field(default=["http://localhost:3000"])
+    log_level: str = Field(default="INFO")
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+settings = Settings()
+```
+
+### main.py — Application Entry
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from src.config import settings
+from src.shared.middleware import setup_middleware
+from src.shared.logger import setup_logging
+from src.modules.user.router import router as user_router
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    setup_logging(settings.log_level)
+    # startup: connect DB, warm caches
+    yield
+    # shutdown: close connections
+
+app = FastAPI(
+    title="Service Name",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+setup_middleware(app, settings)
+app.include_router(user_router, prefix="/api/v1")
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok"}
+```
+
+### router.py — Transport Layer
+```python
+from fastapi import APIRouter, HTTPException, status
+from src.modules.user.schemas import CreateUserRequest, UserResponse
+from src.modules.user.service import UserService
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def create_user(request: CreateUserRequest, service: UserService) -> UserResponse:
+    return await service.create(request)
+```
+
+### schemas.py — Validation Boundaries
+```python
+from pydantic import BaseModel, EmailStr, Field
+from datetime import datetime
+from uuid import UUID
+
+class CreateUserRequest(BaseModel):
+    name: str = Field(min_length=1, max_length=100)
+    email: EmailStr
+    age: int = Field(ge=13, le=150)
+
+    model_config = {"strict": True}
+
+class UserResponse(BaseModel):
+    id: UUID
+    name: str
+    email: str
+    created_at: datetime
+```
+
+### service.py — Business Logic
+```python
+import structlog
+from src.modules.user.schemas import CreateUserRequest, UserResponse
+from src.modules.user.repository import UserRepository
+from src.modules.user.exceptions import UserAlreadyExistsError
+
+logger = structlog.get_logger()
+
+class UserService:
+    def __init__(self, repo: UserRepository) -> None:
+        self._repo = repo
+
+    async def create(self, request: CreateUserRequest) -> UserResponse:
+        if await self._repo.exists_by_email(request.email):
+            raise UserAlreadyExistsError(request.email)
+
+        user = await self._repo.insert(request)
+        logger.info("user_created", user_id=str(user.id), email=user.email)
+        return UserResponse.model_validate(user)
+```
+
+### shared/errors.py — Error Foundation
+```python
+from fastapi import Request, HTTPException
+from fastapi.responses import JSONResponse
+
+class AppError(Exception):
+    def __init__(self, code: str, message: str, status_code: int = 400) -> None:
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+
+async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": {
+                "code": exc.code,
+                "message": exc.message,
+            }
+        },
+    )
+```
+
+---
+
+## Scaffolding Checklist
+
+- [ ] Create project with `pyproject.toml` (ruff, pyright, pytest config)
+- [ ] Set up `src/config.py` with Pydantic Settings
+- [ ] Set up `src/shared/database.py` with async SQLAlchemy engine
+- [ ] Set up `src/shared/errors.py` with base error class + handler
+- [ ] Set up `src/shared/logger.py` with structlog
+- [ ] Create first module following the pattern above
+- [ ] Set up Alembic with initial migration
+- [ ] Create `Makefile` with dev, test, lint, format commands
+- [ ] Create `.env.example`
+- [ ] Create `Dockerfile` (multi-stage)
+- [ ] Run `ruff check` and `pyright` — zero errors

package/.agent-context/blueprints/go-service.md

@@ -0,0 +1,217 @@
+# Blueprint: Go HTTP Service (chi / stdlib)
+
+> Go is not Java. Don't bring Spring patterns.
+> Embrace simplicity, explicit errors, and small interfaces.
+
+## Tech Stack
+
+| Layer | Choice | Why |
+|-------|--------|-----|
+| Language | Go 1.23+ | Latest stable |
+| Router | `net/http` (Go 1.22+ enhanced) + `chi` | stdlib-compatible, composable middleware |
+| Validation | Custom + `go-playground/validator` | Type-safe, struct tags |
+| Database | `database/sql` + `pgx` + `sqlc` | Type-safe queries from SQL |
+| Migrations | `goose` or `golang-migrate` | Versioned, reversible |
+| Logging | `log/slog` (stdlib) | Structured, zero-dependency |
+| Config | `envconfig` or `koanf` | Env-first, typed config |
+| Testing | stdlib `testing` + `testify` (assertions) | Community standard |
+| OpenAPI | `swaggo/swag` or `ogen` | Generate spec from annotations |
+| Telemetry | OpenTelemetry Go SDK | Vendor-neutral observability |
+
+## Project Structure
+
+```
+project-root/
+├── cmd/
+│   └── api/
+│       └── main.go                 # Entry point: wire dependencies, start server
+│
+├── internal/                       # Private application code
+│   ├── config/
+│   │   └── config.go               # Env-based configuration struct
+│   │
+│   ├── domain/                     # Core business types (no external deps)
+│   │   ├── user.go                 # Entity: User
+│   │   ├── order.go                # Entity: Order
+│   │   └── errors.go               # Domain-specific error types
+│   │
+│   ├── service/                    # Business logic (depends on domain + ports)
+│   │   ├── user_service.go
+│   │   └── order_service.go
+│   │
+│   ├── repository/                 # Data access (implements domain ports)
+│   │   ├── postgres/
+│   │   │   ├── user_repo.go
+│   │   │   └── queries/            # sqlc generated or raw SQL
+│   │   └── repository.go           # Interface definitions
+│   │
+│   ├── handler/                    # HTTP handlers (chi routes)
+│   │   ├── user_handler.go
+│   │   ├── order_handler.go
+│   │   ├── middleware.go           # Custom middleware
+│   │   └── response.go            # Standardized JSON response helpers
+│   │
+│   └── platform/                   # Infrastructure adapters
+│       ├── database.go             # Database connection setup
+│       ├── logger.go               # slog configuration
+│       └── telemetry.go            # OpenTelemetry setup
+│
+├── migrations/
+│   ├── 001_create_users.sql
+│   └── 002_create_orders.sql
+│
+├── go.mod
+├── go.sum
+├── Makefile                        # Standard commands
+├── Dockerfile
+└── .env.example
+```
+
+## Key Patterns
+
+### Dependency Injection via Constructors
+
+```go
+// internal/service/user_service.go
+type UserService struct {
+    repo   UserRepository
+    logger *slog.Logger
+}
+
+func NewUserService(repo UserRepository, logger *slog.Logger) *UserService {
+    return &UserService{repo: repo, logger: logger}
+}
+```
+
+### Interfaces in the Consumer Package
+
+```go
+// internal/service/user_service.go
+// Interface defined HERE (consumer), not in the repository package
+type UserRepository interface {
+    FindByID(ctx context.Context, id string) (*domain.User, error)
+    Create(ctx context.Context, user *domain.User) error
+}
+```
+
+### Error Handling: Explicit, Always
+
+```go
+// ❌ BANNED in Go
+result, _ := db.Query(ctx, sql)   // Ignoring error
+
+// ✅ REQUIRED
+result, err := db.Query(ctx, sql)
+if err != nil {
+    return fmt.Errorf("query users: %w", err)
+}
+```
+
+### HTTP Handler Pattern
+
+```go
+// internal/handler/user_handler.go
+func (h *UserHandler) Create(w http.ResponseWriter, r *http.Request) {
+    var req CreateUserRequest
+    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+        respondError(w, http.StatusBadRequest, "invalid request body")
+        return
+    }
+
+    if err := req.Validate(); err != nil {
+        respondError(w, http.StatusBadRequest, err.Error())
+        return
+    }
+
+    user, err := h.service.Create(r.Context(), req.ToDomain())
+    if err != nil {
+        h.logger.ErrorContext(r.Context(), "create user failed",
+            slog.String("error", err.Error()),
+        )
+        respondError(w, http.StatusInternalServerError, "internal error")
+        return
+    }
+
+    respondJSON(w, http.StatusCreated, user)
+}
+```
+
+### Router Setup with chi
+
+```go
+// cmd/api/main.go
+func setupRouter(h *handler.Handler) http.Handler {
+    r := chi.NewRouter()
+
+    // Global middleware
+    r.Use(middleware.RequestID)
+    r.Use(middleware.RealIP)
+    r.Use(middleware.Logger)
+    r.Use(middleware.Recoverer)
+    r.Use(middleware.Timeout(30 * time.Second))
+
+    // API routes
+    r.Route("/api/v1", func(r chi.Router) {
+        r.Route("/users", func(r chi.Router) {
+            r.Get("/", h.User.List)
+            r.Post("/", h.User.Create)
+            r.Route("/{userId}", func(r chi.Router) {
+                r.Get("/", h.User.GetByID)
+                r.Put("/", h.User.Update)
+                r.Delete("/", h.User.Delete)
+            })
+        })
+    })
+
+    // Health check
+    r.Get("/health", func(w http.ResponseWriter, r *http.Request) {
+        w.WriteHeader(http.StatusOK)
+        w.Write([]byte(`{"status":"ok"}`))
+    })
+
+    return r
+}
+```
+
+## Makefile Commands
+
+```makefile
+.PHONY: run build test lint migrate
+
+run:
+	go run ./cmd/api
+
+build:
+	CGO_ENABLED=0 go build -o bin/api ./cmd/api
+
+test:
+	go test ./... -v -race -coverprofile=coverage.out
+
+lint:
+	golangci-lint run ./...
+
+migrate-up:
+	goose -dir migrations postgres "$(DATABASE_URL)" up
+
+migrate-down:
+	goose -dir migrations postgres "$(DATABASE_URL)" down
+
+sqlc:
+	sqlc generate
+```
+
+## Scaffolding Checklist
+
+- [ ] `go mod init` with proper module path
+- [ ] Create `cmd/api/main.go` entry point
+- [ ] Set up `internal/` structure (config, domain, service, repository, handler)
+- [ ] Configure `chi` router with standard middleware stack
+- [ ] Set up `slog` structured logging
+- [ ] Configure database connection with `pgx` + connection pool
+- [ ] Set up `sqlc` for type-safe SQL queries
+- [ ] Create migration files with `goose`
+- [ ] Write standardized JSON response helpers
+- [ ] Add `Makefile` with run, build, test, lint, migrate commands
+- [ ] Create `Dockerfile` (multi-stage, scratch base)
+- [ ] Create `.env.example` with all required env vars
+- [ ] Run `golangci-lint` with strict config

package/.agent-context/blueprints/graphql-grpc-api.md

@@ -0,0 +1,51 @@
+# GraphQL & gRPC API Blueprint
+
+> REST is for resources; GraphQL is for queries; gRPC is for actions. Choose the right tool, then design the contract before writing the code.
+
+## 1. Schema-First Design (Mandatory)
+Never rely on code-first generation for your public contracts.
+- **Rule:** The schema (`.graphql` or `.proto`) is the single source of truth.
+- **Why:** Schema-first forces API design discussions to happen independently of the implementation language. It allows frontend and backend teams to work in parallel.
+- **Validation:** Your CI/CD MUST include a schema linter (e.g., `graphql-schema-linter` or `buf lint`).
+
+## 2. GraphQL Standards
+
+### A. The N+1 Problem (Dataloaders)
+- **Rule:** EVERY resolver that fetches a relation MUST use a DataLoader (or equivalent batching/caching mechanism).
+- **BANNED:** Resolving `author` inside a `posts` query by doing `SELECT * FROM users WHERE id = X` in a loop.
+- **REQUIRED:** Batching IDs to fetch them all in one query `SELECT * FROM users WHERE id IN (X, Y, Z)`.
+
+### B. Pagination
+- **Rule:** Use cursor-based pagination (Relay Connection Specification) for all list endpoints.
+- **BANNED:** Offset-based pagination (`limit`, `offset`) for large datasets (it becomes exponentially slower).
+- **REQUIRED Structure:**
+  ```graphql
+  type UserConnection {
+    edges: [UserEdge!]!
+    pageInfo: PageInfo!
+  }
+  ```
+
+### C. Mutations
+- **Rule:** Mutations MUST represent business actions, not CRUD database operations.
+- **BANNED:** `updateUser`, `createPost`.
+- **REQUIRED:** `suspendUserAccount`, `publishBlogPost`. Every mutation must take a single `input` object and return a `payload` object.
+
+## 3. gRPC & Protobuf Standards
+
+### A. Backwards Compatibility
+- **Rule:** Never rename a field, never change a field's type, and never reuse a field tag number.
+- **BANNED:** `int32 count = 1;` -> `int64 count = 1;`
+- **REQUIRED:** If the type must change, deprecate the old field and create a new one:
+  ```protobuf
+  int32 old_count = 1 [deprecated = true];
+  int64 count = 2;
+  ```
+
+### B. Structure & Organization
+- **Rule:** Group proto files by domain/package (`package ecommerce.orders.v1;`).
+- **Required Files:** Separate messages (`messages.proto`) from services (`service.proto`) if the domain is large.
+
+### C. Error Handling
+gRPC uses standard status codes.
+- **Rule:** Map business errors to explicit `google.rpc.Status` codes. Do not return `UNKNOWN` or `INTERNAL` for business logic failures (like "Insufficient Funds"). Use `FAILED_PRECONDITION` or custom detail payloads.