@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.20

package/.agent-context/rules/architecture.md

@@ -1,17 +1,16 @@
-# Architecture — Separation of Concerns & Structure
+# Architecture - Separation of Concerns and Structure
 
-> If your service file imports an HTTP library, your architecture is broken.
-> If your controller contains SQL, you've already lost.
+> If a service imports transport concerns or raw persistence concerns directly, the architecture is already drifting.
 
 ## Universal Backend Principles (Mandatory)
 
 These principles are mandatory for backend and shared core modules.
 
-- No clever hacks. Prefer explicit control flow over language tricks that hide intent.
-- No premature abstraction. Extract shared utilities or base types only after repeated, stable patterns appear.
-- Readability over brevity. Reject compressed one-liners when clearer multi-line logic is easier to review.
-
-If a short and a clear implementation are functionally equivalent, choose the clear implementation.
+- No clever hacks.
+- No premature abstraction.
+- Readability over brevity.
+- Keep transport, application, domain, and infrastructure concerns separated.
+- Favor explicit module boundaries over hidden cross-layer shortcuts.
 
 ## Universal SOP Baseline (Mandatory)
 
@@ -26,6 +25,7 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
   - If the project uses persistent data, `docs/database-schema.md` must exist.
   - If the project exposes API or web application flows, `docs/api-contract.md` must exist.
   - For UI scope, `docs/DESIGN.md` and `docs/design-intent.json` must exist.
+- Required docs coverage must include feature plan, architecture rationale, public contracts, data model when relevant, UI/design when relevant, security assumptions, testing strategy, delivery flow, and next validation actions.
 - If required project context docs are missing, stop implementation and bootstrap docs before writing application code.
 - Bootstrap flow: analyze the real repo plus the latest user prompt before authoring those docs.
 - Bootstrap docs must be adaptive and project-specific. Do not create generic placeholder templates.
@@ -33,234 +33,67 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
 
 ## Rules as Guardian (Cross-Session Consistency)
 
-These guardrails are mandatory to preserve architecture direction across sessions.
-
 - Session handoff must include active architecture contract summary.
-- Contract summary must include declared stack, blueprint, profile, and active core patterns.
-- Detect drift before changing declared stack or core patterns.
+- Contract summary must include explicit user constraints, runtime/architecture decision status, active project docs, and the core patterns currently evidenced by the repo.
+- Detect drift before changing runtime choices, topology, public contracts, or core patterns.
 - Direction changes require explicit user confirmation before applying changes.
 - When confirmation is provided, record the rationale in session notes or PR context.
 
 ## Invisible State Management with Explain-on-Demand
 
-State internals must stay invisible by default.
-
 - Default responses must avoid unnecessary state-file internals.
 - State internals are exposed only on explicit user request.
 - Diagnostic mode explains relevant state decisions when needed.
-- Keep default explanations concise and outcome-first; show raw state details only in diagnostic mode.
+- Keep default explanations concise and outcome-first.
 
 ## Single Source of Truth and Lazy Rule Loading
 
 - Canonical rule source is .instructions.md.
 - Adapter entry files stay thin and must point to the canonical source.
 - Load language-specific stack guidance lazily based on detected scope.
+- Load language-specific or framework-specific guidance lazily based on changed files, explicit constraints, and repo evidence.
 - Do not preload unrelated stack profiles during normal flow.
 - Keep rule-loading output deterministic for init and release validation.
 
-## The Core Principle
-
-**Every layer has ONE job. Layer leaks are bugs — not "pragmatic shortcuts."**
-
-```
-┌─────────────────────────────────────────┐
-│         TRANSPORT / CONTROLLER          │  ← Parse input, validate shape, return response
-│         (HTTP, CLI, WebSocket, Queue)   │  ← NO business logic here. EVER.
-├─────────────────────────────────────────┤
-│         APPLICATION / SERVICE           │  ← Business rules, orchestration, transactions
-│         (Use cases, workflows)          │  ← NO HTTP, NO SQL, NO framework imports
-├─────────────────────────────────────────┤
-│         DOMAIN / ENTITY                 │  ← Pure business objects, value objects
-│         (Models, rules, calculations)   │  ← ZERO external dependencies
-├─────────────────────────────────────────┤
-│         INFRASTRUCTURE / REPOSITORY     │  ← Database, external APIs, file system
-│         (Data access, adapters)         │  ← NO business logic
-└─────────────────────────────────────────┘
-```
-
-## Layer Rules (Enforced)
-
-### Transport Layer (Controller / Handler / Route)
-**Allowed:**
-- Parse and validate incoming request (DTO/schema validation)
-- Call application/service layer
-- Format and return HTTP response (status code, headers)
-- Handle authentication/authorization middleware
-
-**BANNED:**
-- Database queries or ORM calls
-- Business logic (if/else on business rules)
-- Direct calls to external APIs
-- Transaction management
+## Architecture Decision Boundary
 
-### Application Layer (Service / Use Case)
-**Allowed:**
-- Orchestrate business operations
-- Call repository layer for data
-- Apply business rules and validations
-- Manage transactions
-- Emit domain events
+Do not force a default architecture label before the repo, delivery model, and boundary evidence are clear.
 
-**BANNED:**
-- HTTP request/response objects
-- Framework-specific decorators (keep framework coupling minimal)
-- Direct SQL or raw database calls
-- UI/presentation logic
+Do not split into distributed services without evidence. Do not keep everything in one process by habit either.
 
-### Domain Layer (Entity / Value Object)
-**Allowed:**
-- Business calculations and rules
-- Validation of domain invariants
-- Type definitions and interfaces
+Service separation only makes sense when multiple signals are true, such as:
 
-**BANNED:**
-- ANY external dependency (database, HTTP, framework)
-- Side effects (logging, API calls, file I/O)
-- Infrastructure concerns
+- frequent deploy conflicts across domains
+- clear scale mismatch between domains
+- separate team ownership causing repeated coupling pain
+- hard fault-isolation requirements
+- already-stable contracts and data boundaries
 
-### Infrastructure Layer (Repository / Adapter)
-**Allowed:**
-- Database queries (SQL, ORM, document queries)
-- External API calls (wrapped in adapters)
-- File system operations
-- Cache operations
+## Layer Boundaries (Mandatory)
 
-**BANNED:**
-- Business logic (no if/else on business rules in queries)
-- HTTP response formatting
-- Direct exposure to transport layer
-
----
+- Transport or controller layer: parse input, validate shape, enforce auth at the edge, return protocol responses. No business policy, no raw SQL, no external workflow orchestration.
+- Application or service layer: business rules, orchestration, transactions, and use-case flow. No request or response objects, no UI formatting, no raw transport dependencies.
+- Domain layer: pure business invariants, calculations, value objects, and policies. No framework, network, database, or file-system coupling.
+- Infrastructure or repository layer: database, queue, cache, file system, and external API adapters. No business policy hidden in queries or adapters.
 
 ## Dependency Direction
 
-Dependencies flow **inward only**:
-
-```
-Transport → Application → Domain ← Infrastructure
-                ↓
-          Infrastructure
-
-NEVER: Domain → Infrastructure (use interfaces/ports)
-NEVER: Application → Transport
-NEVER: Infrastructure → Application (except through interfaces)
-```
-
-The Domain layer depends on NOTHING. Everything depends on the Domain.
-
----
-
-## Default Architecture: Modular Monolith
-
-Start with a **Modular Monolith**. Do NOT start with microservices.
+- Dependencies flow inward: transport to application to domain.
+- Infrastructure depends inward through interfaces or well-defined ports.
+- Domain must not depend on infrastructure.
+- Application must not depend on transport details.
 
-**Switch to microservices ONLY if 2+ of these triggers exist:**
-1. Frequent deploy conflicts across domains (teams blocking each other)
-2. Clear scale mismatch (one module needs 100x resources of another)
-3. Team ownership collision (multiple teams editing same module)
-4. Fault isolation requirement (one module crashing must not kill others)
-5. Stable contracts with clear data boundaries already exist
+## Project Structure and File Size Discipline
 
-If these triggers don't exist, microservices are **premature complexity**.
-
----
-
-## Project Structure: Feature-Based Grouping
-
-## Code Organization and File Size Discipline
-
-Keep modules small enough to understand in one focused read.
-
-- Prefer grouping by responsibility, not by convenience.
-- One folder should represent one clear area of responsibility.
-- Split discovery, validation, prompt building, persistence, and contract logic into separate modules when they grow.
-- Avoid mixed-purpose mega-files that combine constants, parsing, orchestration, validation, and I/O in one place.
-- Treat files above roughly 1000 lines as a refactor trigger, not a badge of completeness.
-- If a file grows past that threshold, extract stable submodules with clear names before adding more behavior.
-- Preserve one public entrypoint when it helps callers, but move the real implementation behind focused modules.
-- Tests may aggregate scenarios, but shared helpers and repeated setup should move into dedicated support files when the suite becomes hard to scan.
-
-### ❌ BANNED: Technical Grouping
-```
-src/
-  controllers/          ← 50 controllers in one flat folder?
-    userController.ts
-    orderController.ts
-    paymentController.ts
-  services/             ← Good luck finding related code
-    userService.ts
-    orderService.ts
-  repositories/
-    userRepository.ts
-    orderRepository.ts
-```
-
-### ✅ REQUIRED: Feature/Domain Grouping
-```
-src/
-  modules/                              ← Backend
-    user/
-      user.controller.ts               ← Transport
-      user.service.ts                   ← Application
-      user.repository.ts               ← Infrastructure
-      user.entity.ts                    ← Domain
-      user.dto.ts                       ← Data Transfer Objects
-      user.module.ts                    ← Module registration
-      __tests__/
-        user.service.test.ts
-    order/
-      order.controller.ts
-      order.service.ts
-      ...
-  shared/                               ← Cross-cutting concerns
-    config/
-    errors/
-    logging/
-    middleware/
-
-src/
-  features/                             ← Frontend
-    payment/
-      api/                              ← HTTP client + DTOs
-      hooks/                            ← React hooks / state
-      components/                       ← UI components
-      types/                            ← Type definitions
-      utils/                            ← Feature-specific utils
-      index.ts                          ← Public API barrel
-  components/
-    ui/                                 ← Shared UI primitives
-    layout/                             ← Layout components
-  lib/                                  ← Shared utilities
-  config/                               ← App configuration
-```
-
----
+- Group code by feature or domain, not by one giant technical folder per type.
+- Backend feature modules use `src/modules/<feature>/...` when the repo has no stronger existing convention.
+- Frontend feature modules use `src/features/<feature>/...` when the repo has no stronger existing convention.
+- Cross-cutting utilities belong in explicit shared locations, not scattered feature internals.
+- Files above roughly 1000 lines are a refactor trigger, not a success signal.
+- Preserve one clear public entrypoint per module when helpful, but move implementation into smaller focused files.
 
 ## Module Communication
 
-### Within a Monolith
-Modules communicate through **public interfaces only**:
-```
-// ✅ CORRECT: Import from module's public API
-import { UserService } from '@/modules/user';
-
-// ❌ BANNED: Reach into another module's internals
-import { UserRepository } from '@/modules/user/user.repository';
-```
-
-### Between Services (if microservices)
-- Use well-defined contracts (REST, gRPC, events)
-- Never share databases between services
-- Define schemas at boundaries (Protobuf, JSON Schema, Zod)
-
----
-
-## The Architecture Smell Test
-
-Ask yourself these questions. If ANY answer is "yes", your architecture is broken:
-
-1. Can I change the database without touching business logic? (Must be YES)
-2. Can I switch from REST to GraphQL without rewriting services? (Must be YES)
-3. Can I test business logic without a running database? (Must be YES)
-4. Does each module have a clear, single responsibility? (Must be YES)
-5. Can a new developer find all related code in one directory? (Must be YES)
+- Import through a module's public API instead of reaching into internal files.
+- Keep contracts explicit at boundaries between modules.
+- If a new developer cannot find the full flow of a feature in one clear area, the structure is too diffuse.

package/.agent-context/rules/database-design.md

@@ -1,202 +1,13 @@
-# Database Design — Schema Is Your Foundation
+# Data Design Boundary
 
-> A poorly designed schema is a bug factory.
-> You can fix bad code in hours. A bad schema takes weeks.
+Use the data store, ORM, migration tool, and query style already chosen by the project. If unresolved, the LLM must recommend a current fit from requirements, repo evidence, and official docs before implementation.
 
-## Normalization Rules
+Reject these bad habits:
+- schema changes without a migration, rollback or recovery note, and data-safety plan
+- duplicated facts or derived values without a sync strategy and rationale
+- unbounded reads or missing pagination on growable datasets
+- missing indexes or access-path planning for frequent filters, joins, lookups, search, or ordering
+- raw query construction that bypasses safe parameterization
+- destructive data changes without backup, migration, or deployment sequencing notes
 
-### Third Normal Form (3NF) is the Default
-
-```
-❌ BANNED: Flat tables with repeated data
-Users:
-  | id | name  | order_id | order_total | product_name |
-  | 1  | Jane  | 101      | 99.99       | Widget       |
-  | 1  | Jane  | 102      | 49.99       | Gadget       |
-  → name is duplicated, update anomalies guaranteed
-
-✅ REQUIRED: Normalized to 3NF
-Users:    | id | name  | email          |
-Orders:   | id | user_id | total | status |
-Products: | id | name   | price |
-OrderItems: | order_id | product_id | quantity |
-  → Each fact is stored exactly once
-```
-
-### When to Denormalize
-
-Denormalization is allowed ONLY with documented justification:
-
-1. **Read-heavy query** that joins 4+ tables and is called >1000x/sec
-2. **Reporting/analytics** where query speed matters more than write consistency
-3. **CQRS read model** that is purpose-built for a specific query
-
-```
-REQUIRED for every denormalization:
-- Document WHY (link to performance evidence)
-- Document HOW it stays in sync (trigger, event, scheduled job)
-- Add a comment in the schema: "Denormalized for [query name], synced by [mechanism]"
-```
-
----
-
-## Indexing Strategy
-
-### Rules of Indexing
-
-1. **Every foreign key gets an index** — joins on unindexed FKs are full table scans
-2. **Every WHERE clause in a frequent query gets evaluated** — if the column appears in WHERE and the table has >10K rows, consider an index
-3. **Composite indexes matter** — `INDEX(status, created_at)` ≠ `INDEX(created_at, status)`. Column order follows the query pattern (most selective first, or matching WHERE + ORDER BY)
-4. **Covering indexes** — include frequently selected columns to avoid table lookups
-
-### What to Index
-
-| Pattern | Index Type | Example |
-|---------|-----------|---------|
-| FK lookups | B-tree (default) | `orders.user_id` |
-| Status + date filters | Composite | `INDEX(status, created_at)` |
-| Full-text search | Full-text / GIN | `products.description` |
-| JSON queries | GIN (PostgreSQL) | `metadata->>'type'` |
-| Unique constraints | Unique | `users.email` |
-| Geospatial | Spatial / GiST | `locations.coordinates` |
-
-### What NOT to Index
-
-- Columns with very low cardinality on small tables (`is_active` with 2 values on 100 rows)
-- Tables with <1000 rows (index overhead > benefit)
-- Write-heavy tables where every INSERT updates 10+ indexes
-- Columns never used in WHERE, JOIN, or ORDER BY
-
-### Index Monitoring
-
-```
-REQUIRED:
-- Identify unused indexes monthly → DROP them (they slow writes)
-- Identify missing indexes → EXPLAIN ANALYZE on slow queries
-- Track index size vs table size → alarming if indexes > 3x table size
-```
-
----
-
-## Migration Standards
-
-### Rules
-
-1. **Every schema change is a migration** — never modify production schemas manually
-2. **Migrations are versioned and sequential** — `001_create_users.sql`, `002_add_email_index.sql`
-3. **Migrations are idempotent** — running twice produces the same result
-4. **Migrations are reversible** — every UP has a DOWN (or document why rollback is impossible)
-5. **Migrations run in CI** — test against a real database, not just syntax checks
-
-### Safe Migration Patterns
-
-```
-✅ SAFE (no downtime):
-1. ADD COLUMN with default (nullable or with DEFAULT)
-2. CREATE INDEX CONCURRENTLY
-3. ADD new table
-4. Rename via view + synonym (transitional)
-
-❌ DANGEROUS (requires planned downtime or careful orchestration):
-1. DROP COLUMN (deploy code changes removing column usage FIRST)
-2. RENAME COLUMN (use gradual rename: add new → copy data → remove old)
-3. ALTER COLUMN TYPE (may lock table on large datasets)
-4. DROP TABLE (ensure no code references remain)
-```
-
-### The Expand-Contract Pattern
-
-For breaking schema changes in zero-downtime deployments:
-
-```
-Phase 1 (Expand): Add new column/table alongside old one
-   → Code writes to BOTH old and new
-Phase 2 (Migrate): Backfill data from old to new
-   → Verify data consistency
-Phase 3 (Contract): Remove old column/table
-   → Code reads/writes only new
-```
-
----
-
-## Data Type Selection
-
-### Use the Right Type
-
-| Data | ❌ Wrong | ✅ Right | Why |
-|------|---------|---------|-----|
-| Money | `FLOAT` | `DECIMAL(19,4)` or integer cents | Floating point arithmetic is imprecise |
-| UUID | `VARCHAR(36)` | `UUID` native type | 16 bytes vs 36 bytes, indexing is faster |
-| Timestamps | `VARCHAR` | `TIMESTAMPTZ` | Timezone-aware, sortable, comparable |
-| IP addresses | `VARCHAR(45)` | `INET` (PostgreSQL) | Validation built-in, range queries |
-| Boolean | `INT` (0/1) | `BOOLEAN` | Semantic clarity |
-| Enums | `VARCHAR` | Database ENUM or CHECK constraint | Prevents invalid values |
-| JSON blobs | `TEXT` | `JSONB` (PostgreSQL) | Indexable, queryable, validated |
-
-### Column Naming
-
-```
-✅ REQUIRED:
-- snake_case for all column names
-- Descriptive: created_at, updated_at, deleted_at (not ts, mod, del)
-- Foreign keys: {referenced_table_singular}_id (e.g., user_id, order_id)
-- Boolean columns: is_active, has_verified_email, can_edit
-- Timestamps: {verb}_at (created_at, verified_at, shipped_at)
-- Amounts: {noun}_amount or {noun}_cents (total_amount, tax_cents)
-```
-
----
-
-## Query Design Rules
-
-### Pagination (Mandatory for Lists)
-
-```
-❌ BANNED:
-SELECT * FROM orders;
--- Returns 2 million rows, OOM crash
-
-✅ REQUIRED: Offset pagination (simple, okay for < 100K rows)
-SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 40;
-
-✅ PREFERRED: Cursor pagination (performant at any scale)
-SELECT * FROM orders WHERE id > :last_seen_id ORDER BY id LIMIT 20;
-```
-
-**Rule:** Use cursor-based pagination for tables > 100K rows. Offset pagination degrades linearly with OFFSET value.
-
-### Soft Deletes vs Hard Deletes
-
-```
-Use soft deletes (deleted_at column) when:
-- Legal/compliance requires data retention
-- Users might want to "undelete"
-- Related data would break without the parent record
-
-Use hard deletes when:
-- GDPR/privacy requires actual data removal
-- Data has no business value after deletion
-- Storage cost of keeping data outweighs benefit
-
-If soft deleting:
-- Add deleted_at to ALL queries: WHERE deleted_at IS NULL
-- Add a partial index: WHERE deleted_at IS NULL (for performance)
-- Schedule periodic hard-delete of old soft-deleted records
-```
-
----
-
-## The Database Design Checklist
-
-Before any schema goes to production:
-
-- [ ] Schema is normalized to 3NF (denormalization documented if present)
-- [ ] All foreign keys have indexes
-- [ ] Primary keys use appropriate type (UUID or BIGINT)
-- [ ] Timestamps use TIMESTAMPTZ (not VARCHAR)
-- [ ] Money uses DECIMAL or integer cents (never FLOAT)
-- [ ] Migration is versioned, reversible, and tested in CI
-- [ ] All list queries have LIMIT (pagination implemented)
-- [ ] Indexes justified with EXPLAIN ANALYZE on expected queries
-- [ ] Column naming follows convention (snake_case, descriptive)
-- [ ] Soft delete vs hard delete decision documented
+Docs must record entity ownership, relationships, constraints, data lifecycle, migration risk, and assumptions to validate.

package/.agent-context/rules/docker-runtime.md

@@ -4,16 +4,16 @@ Use this rule when Docker is enabled in project context.
 
 ## 0. Latest Official Docker Guidance First
 - Before generating or changing Dockerfiles, Compose files, or container runbooks, verify the latest official Docker documentation first.
-- Prefer official Docker sources such as [Docker Compose Quickstart](https://docs.docker.com/compose/gettingstarted/), [Compose file reference](https://docs.docker.com/reference/compose-file/), and [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/).
-- Prefer current `docker compose` workflows and `compose.yaml`. Do not default to legacy `docker-compose` commands or stale file naming unless backward compatibility is a stated project requirement.
+- Use official Docker sources such as [Docker Compose Quickstart](https://docs.docker.com/compose/gettingstarted/), [Compose file reference](https://docs.docker.com/reference/compose-file/), and [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/).
+- Use current `docker compose` workflows and `compose.yaml`. Do not default to legacy `docker-compose` commands or stale file naming unless backward compatibility is a stated project requirement.
 - Do not add the top-level Compose `version` field by default. The current Compose reference treats it as obsolete. Use it only when a compatibility requirement is explicit and documented.
-- Prefer the latest stable compatible Docker base image, package-manager flow, and Compose syntax first. If the latest compatible path fails, step down intentionally and document the exact reason for the fallback.
+- Use the latest stable compatible Docker base image, package-manager flow, and Compose syntax first. If the latest compatible path fails, step down intentionally and document the exact reason for the fallback.
 
 ## 1. Dynamic Generation Only
 - Do not copy generic Docker templates blindly.
 - Generate Docker assets based on actual stack, package manager, and runtime dependencies in the repository.
 - Re-evaluate Docker instructions when dependencies, build tools, or runtime assumptions change.
-- Prefer the latest stable compatible dependency line first. If an older dependency or base image must be pinned, explain the runtime or compatibility constraint that forced it.
+- Use the latest stable compatible dependency line first. If an older dependency or base image must be pinned, explain the runtime or compatibility constraint that forced it.
 
 ## 2. Separate Development and Production Lanes
 - Development lane and production lane are separate concerns.
@@ -25,7 +25,7 @@ Use this rule when Docker is enabled in project context.
 - Use multi-stage builds for production images when possible.
 - Avoid baking secrets into image layers.
 - Keep runtime image free from build-only tooling.
-- Prefer fresh base-image validation with `docker build --pull` and use `--no-cache` when a clean dependency refresh is required.
+- Use fresh base-image validation with `docker build --pull` and use `--no-cache` when a clean dependency refresh is required.
 - Keep a `.dockerignore` strategy in mind so build contexts stay small and do not leak unnecessary files into the image.
 
 ## 4. Operational Clarity