@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.20

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

@@ -1,119 +1,66 @@
-# Frontend Architecture & Composition Patterns
-
-> A complex UI is built from simple, mathematically robust functions. State is dangerous; isolate it.
-
-## 0. Frontend Designer Mode (Auto Activation)
-When the user request is UI-facing, frontend design governance activates automatically. No manual mode toggle is required.
-
-UI scope trigger signals (any one is enough):
-- keywords such as: ui, ux, page, screen, component, layout, landing, dashboard, form, onboarding, animation, interaction
-- explicit requests to improve visual quality, conversion clarity, or interaction behavior
-- feature requests that include frontend deliverables even when backend changes are also included
-
-Mandatory behavior when triggered:
-- apply consolidated review checks from `.agent-context/review-checklists/pr-checklist.md`
-- apply structural checks from `.agent-context/review-checklists/architecture-review.md`
-- score and review generated UI work against visual intent, interaction quality, and conversion clarity
-- reject template-only repetitive outputs and force a distinct layout direction
-- treat prior website memory or old-project visual carryover as invalid evidence unless the user explicitly requests continuity with that exact system
-- do not flatten ambitious visual or motion ideas by default; keep them when they are optimized, intentional, and accessible
-- let current repo evidence, the active brief, current project docs, and explicitly approved reference systems outrank remembered style residue every time
-
-## Context Hygiene and Reference Boundaries (Mandatory)
-
-- Valid visual-context sources are limited to the current repo evidence, the current user brief, current project docs, and explicitly approved reference systems.
-- Design continuity is opt-in. If the user does not request continuity with a prior visual system, synthesize from the current project context instead.
-- Old project screenshots, remembered website styles, and cross-chat visual residue are tainted context unless the user explicitly authorizes them.
-- When repo evidence and memory residue conflict, repo evidence wins.
-- If a reference system is approved, adapt its reasoning and constraints. Do not copy its surface 1:1.
-
-## Accessibility Split (Mandatory)
-
-- Treat WCAG 2.2 AA as the hard compliance floor for release-blocking accessibility issues.
-- Treat APCA as an advisory readability model for perceptual tuning, especially for typography, dark mode, and nuanced contrast review.
-- Advisory APCA findings must never waive a WCAG hard failure.
-- Hard accessibility checks must cover more than contrast alone. They must include focus visibility, focus appearance, target size, keyboard access, use-of-color-only failures, accessible authentication, and status or dynamic state access.
-- Keep accessibility compatible with expressive design. Fix the violation without flattening the interface into generic low-risk layouts unless that is the only safe option.
-
-## Hybrid Visual QA Boundaries (Mandatory)
-
-- Visual QA must be deterministic-first. Run screenshot or pixel-diff style checks before escalating to any semantic judge.
-- Treat dynamic masking as explicit policy, not ad hoc cleanup. Time, randomized content, live counters, streaming media, and other unstable regions must be masked deliberately and documented.
-- Define stability thresholds so the system can separate tiny rendering noise from meaningful layout or styling drift.
-- Required visual coverage must include mobile, tablet, and desktop unless the product scope explicitly excludes one of those surfaces.
-- Escalate to semantic review only when deterministic evidence shows meaningful drift, missing required viewport coverage, or another contract-critical visual failure.
-- Do not use semantic review to invent aesthetic problems when deterministic evidence says the surface is stable.
-
-## UI Consistency Guardrails (Mandatory)
-
-- Content language must stay consistent per screen and flow unless user requests multilingual output.
-- Text color must remain contrast-safe against its background; no color collisions.
-- Layout must avoid overlap, clipped text, and misaligned key actions across breakpoints.
-- Responsive quality requires layout mutation and task reprioritization across breakpoints. Shrinking the desktop layout is not enough.
-- Keep spacing and positioning token-driven so repeated outputs stay stable.
-- Distinctive visual direction is allowed. Originality is a quality signal when hierarchy, task clarity, and accessibility still hold.
-- Motion is allowed to be expressive. Judge it by clarity, reduced-motion safety, and rendering cost, not by how restrained it looks.
-- Prefer transform and opacity for rich motion. Treat layout-thrashing animation, uncontrolled autoplay, and heavy continuous effects as optimization problems to solve, not reasons to remove personality from the UI entirely.
-
-## 1. File Structure (Feature-Driven Design)
-Organize your application by feature domain, not by file type.
-- **BANNED:** Monolithic directories like `/components` (with 500 files), `/hooks`, `/api`.
-- **REQUIRED (Feature Sliced):**
-  ```
-  src/
-    features/
-      authentication/
-        api/          #(login, logout fetchers)
-        components/   #(LoginForm, ProfileView)
-        hooks/        #(useAuth, useSession)
-        store.ts      #(Zustand slice)
-        types.ts      #(Zod schemas)
-    components/       #(Global shared UI like Button, Modal)
-    lib/              #(Axios instance, utility wrappers)
-  ```
-
-## 2. Separation of State and UI (Smart vs. Dumb)
-- **Dumb Components (Presentational):** Receive data via `props`, emit events via callbacks (`onAction`). They do not know about the network, global context, or databases.
-- **Smart Components (Containers):** Connect to global state (Redux/Zustand), fetch data (React Query), and pass it down.
-- **Rule:** An intricate UI layout component should NEVER contain a `fetch` or `useQuery` call.
-
-## 3. Server State vs. Client State
-Modern frontend frameworks differentiate between remote and local data.
-- **Server State (Async, Cached):** Data belonging to the database. MUST be managed by tools like `TanStack Query` (React Query) or `SWR`.
-- **Client State (Sync, Ephemeral):** UI toggles, modal states, form drafts. Manage via `useState`, `useContext`, or `Zustand`.
-- **BANNED:** Storing API responses in a global Redux/Zustand store (e.g., `dispatch(setUsers(data))`). Use React Query instead.
-
-## 4. The Composition Pattern (Avoiding Prop Drilling)
-If a component takes more than 5 props, or if props are passed down through 3+ intermediate components, the architecture is broken.
-- **BANNED:** `<Layout user={user} theme={theme} onLogout={handleLogout} />`
-- **REQUIRED:** Use React's `children` prop and composition.
-  ```tsx
-  // ✅ Clean composition
-  <Layout>
-    <Sidebar user={user} />
-    <Content onLogout={handleLogout} />
-  </Layout>
-  ```
-
-## 5. Explicit Component Contracts (Typing)
-Every component **MUST** have an explicit, exported interface for its props.
-- **BANNED:** `const Button = (props: any) => ...`
-- **REQUIRED:** Prefix handlers with `on` and booleans with `is/has`.
-  ```typescript
-  export interface ButtonProps {
-    variant: 'primary' | 'secondary';
-    isLoading?: boolean;
-    onClick: () => void;
-    children: React.ReactNode;
-  }
-  ```
-
-## 6. Form Handling & Validation
-Never write manual state bindings for complex forms.
-- **Rule:** All forms MUST use a robust library (`react-hook-form` is the standard) combined with a schema validator (`Zod`).
-- **BANNED:** Creating 5 `useState` variables for 5 input fields.
-
-## 7. Performance & Re-renders
-React is fast until you break it.
-- **Rule:** Do not pass newly instantiated objects or arrow functions directly into dependency arrays (`useEffect`) or memoized components (`React.memo`) unless wrapped in `useMemo`/`useCallback`.
-- **Rule:** Never execute expensive mapping/filtering inside the render path blindly without memoization.
+# Frontend Design and Interaction Boundaries
+
+UI work must load the smallest relevant surface, not the entire engineering handbook.
+
+## Auto Activation
+When the request is UI-facing, this rule activates automatically.
+
+UI scope triggers:
+- ui, ux, page, screen, component, layout, landing, dashboard, form, onboarding, animation, interaction
+- redesign, reskin, visual refresh, responsive fix, hierarchy fix
+- frontend deliverables even when the task also touches backend code
+
+## What This Rule Is For
+Use this file to enforce:
+- anti-generic layout and morphology boundaries
+- responsive mutation requirements
+- accessibility floor for expressive UI
+- source hygiene for visual decisions
+- lightweight implementation boundaries that keep UI code from collapsing into framework defaults
+
+Do not use this file to teach generic frontend basics the model already knows.
+
+## Source Hygiene and Source Boundaries
+
+- Valid style context is limited to current repo evidence, the active brief, and current project docs.
+- This rule guides the LLM; it must not choose the final style, framework, palette, typography, layout paradigm, or animation library offline.
+- Design continuity is opt-in. If the user does not request continuity, synthesize from the current product context instead of remembered layouts.
+- Repo evidence outranks memory residue every time.
+- External references are tainted by default. If the user supplies one, convert only explicit constraints into the current contract and do not compare against or imitate the source surface.
+- If a new UI, animation, styling, or component library is needed, research current official docs and choose the latest stable compatible option for the project.
+
+## Accessibility Split
+
+- Treat WCAG 2.2 AA as the hard compliance floor.
+- Treat APCA as advisory perceptual tuning only.
+- Hard checks must include focus visibility, focus appearance, target size, keyboard access, accessible authentication, use-of-color-only failures, and dynamic status/state access.
+- Fix the violation without flattening the interface into generic safe chrome unless that is the only safe option.
+
+## Anti-Generic UI Boundaries
+
+- Do not default to interchangeable dashboard chrome, balanced card grids, centered marketing shells, or generic component-kit surfaces unless the product explicitly needs them.
+- Do not let repeated surfaces share the same visual treatment by habit. Repetition is allowed only when the contract explains the product reason.
+- Do not use default framework button and input treatment as the final UI language.
+- Do not let heading, body, and data/meta roles collapse into one safe typographic family without explicit rationale.
+- At least one visual, interaction, content, motion, or state behavior must read as project-specific at a glance.
+
+## Responsive Mutation Requirements
+
+- Responsive quality is not allowed to be scale-only. At least one surface must materially change position, grouping, priority, or disclosure strategy between mobile and desktop.
+- Mobile must prioritize the first decisive action, not preserve desktop balance out of habit.
+- Tablet must simplify simultaneous surfaces without becoming a shrunken desktop.
+- Desktop may expose more context, but it must not become an interchangeable admin shell by default.
+
+## Surface and Morphology Requirements
+
+- Define the primary user task or reading path from current evidence before arranging surfaces.
+- Supporting surfaces must earn their placement through role, priority, or behavior. They must not feel like cloned modules.
+- Component states must preserve identity under hover, focus, loading, success, empty, and error. Do not let everything collapse into anonymous rounded panels.
+- Motion may be expressive, but it must strengthen hierarchy, feedback, or memorability while staying reduced-motion-safe and performant.
+
+## Implementation Boundaries
+
+- Follow the shipped project stack and current repo patterns before inventing state-management or data-fetching rules.
+- Do not hardcode Zustand, React Query, smart/dumb component doctrine, or any framework-specific architecture as universal frontend law in baseline design governance.
+- If the repo already uses a runtime pattern, stay consistent with it. If it does not, choose the lightest modern fit for the task and document why.
+- Keep structure feature-oriented and avoid giant catch-all UI buckets when the repo does not explicitly require them.

package/.agent-context/rules/git-workflow.md

@@ -26,7 +26,7 @@
 
 ### Rules
 1. **Type is mandatory.** No commits without a type prefix.
-2. **Scope is recommended.** Use the module/feature name.
+2. **Scope is required for module or feature changes.** Use the module/feature name.
 3. **Description is imperative mood.** "add", not "added" or "adds".
 4. **Max 72 characters** for the subject line.
 5. **Body explains WHY,** not what. The diff shows what.

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

@@ -1,174 +1,41 @@
-# Microservices — When to Split, How to Split
+# Service Boundary Rule
 
-> Don't start with microservices. Earn them through pain.
-> A bad monolith becomes a distributed bad monolith faster than you think.
+Do not ask for or force "monolith vs microservices" as an init default. Do not start with microservices by fashion, fear, or habit. The agent must infer the right topology from the user brief, repo evidence, team/runtime constraints, and live official docs when technology choices matter.
 
-## The Default: Modular Monolith
+## Monolith Boundary
 
-**Start with a modular monolith. Always.** Microservices are a scaling strategy, not a design philosophy.
+Use a single deployable system when:
 
-A well-structured modular monolith can handle most applications indefinitely. Splitting prematurely creates distributed complexity without distributed benefits.
+- one team or one delivery stream owns most changes
+- feature boundaries can stay clear inside one repo/process
+- synchronous data consistency is more valuable than distributed autonomy
+- observability, CI/CD, and operational maturity are still forming
 
----
+Hard rules:
 
-## The Split Decision Framework
+- Keep feature/domain boundaries explicit.
+- Do not let one giant shared module become the real architecture.
+- Keep contracts clear between modules.
+- Refactor toward cleaner seams before extracting services.
 
-### Prerequisites (ALL Must Be True)
+## Service Split Boundary
 
-Before even considering microservices, these must exist:
+Split a service only when current evidence justifies the operational cost.
 
-1. **Mature CI/CD pipeline** — automated testing, deployment, rollback
-2. **Observability in place** — distributed tracing, centralized logging, metrics
-3. **Team maturity** — team understands distributed systems failure modes
-4. **Clear module boundaries** — modules already communicate through interfaces, not internals
+Valid split signals:
 
-If any prerequisite is missing, **stop.** Fix the monolith first.
+- independent deploy cadence is already painful
+- one domain has materially different scale, latency, security, or compliance needs
+- ownership boundaries are stable and repeated coupling is causing delivery risk
+- failure isolation is a real product or business requirement
+- the service contract and data ownership can be documented before extraction
 
-### Trigger Conditions (2+ Required)
+Hard rules:
 
-Split a module into a service ONLY when **2 or more** of these triggers exist:
+- Each service owns its data boundary.
+- Public service contracts must be documented before implementation or extraction.
+- Cross-service calls need timeout, retry, idempotency, observability, and recovery behavior.
+- Avoid synchronous call chains that turn services into a distributed monolith.
+- Prefer incremental extraction over rewrites.
 
-| # | Trigger | Evidence |
-|---|---------|----------|
-| 1 | **Deploy conflicts** | Teams block each other on releases; merge queues exceed 24h |
-| 2 | **Scale mismatch** | One module needs 50-100x resources of another |
-| 3 | **Team ownership collision** | Multiple teams edit the same module weekly |
-| 4 | **Fault isolation** | One module crashing must not kill the entire system |
-| 5 | **Technology divergence** | Module genuinely requires a different runtime/language |
-| 6 | **Compliance boundary** | Regulatory requirement to isolate data processing (PCI, HIPAA) |
-
-```
-BANNED: "Let's use microservices because Netflix does"
-BANNED: "We might need to scale later"
-BANNED: "It's more modern"
-BANNED: "Each developer gets their own service"
-```
-
----
-
-## How to Split (The Extraction Protocol)
-
-### Step 1: Identify the Seam
-
-Find the natural boundary in your modular monolith:
-```
-GOOD seams:
-  - Module communicates with others through a defined interface/API
-  - Module has its own database tables with no foreign keys to other modules
-  - Module can be deployed independently without breaking others
-
-BAD seams:
-  - Two modules share a database table
-  - Extracting requires duplicating business logic
-  - Module makes 10+ synchronous calls to other modules per request
-```
-
-### Step 2: Strangle, Don't Rewrite
-
-```
-❌ BANNED: "Let's rewrite everything as microservices"
-
-✅ REQUIRED: The Strangler Fig Pattern
-1. Build the new service alongside the monolith
-2. Route traffic to the new service gradually (feature flags, proxy rules)
-3. Verify the new service handles all cases correctly
-4. Remove the old code from the monolith
-5. Repeat for the next service, ONE AT A TIME
-```
-
-### Step 3: Define the Contract
-
-Before extracting, define the communication contract:
-
-```
-REQUIRED for every service boundary:
-- API contract (OpenAPI 3.1, Protobuf, or AsyncAPI for events)
-- Versioning strategy (URL versioning, header versioning)
-- Error contract (standardized error response format)
-- SLA definition (latency, availability, throughput)
-- Ownership (which team owns this service)
-```
-
----
-
-## Communication Patterns
-
-### Synchronous (Request-Response)
-
-| Pattern | When | Watch Out |
-|---------|------|-----------|
-| REST/HTTP | Standard CRUD operations | Cascading failures, tight coupling |
-| gRPC | High-performance, internal services | Schema evolution, debugging complexity |
-
-**Rules:**
-- Always set timeouts (connection: 1s, request: 5s default)
-- Implement circuit breakers (fail-fast after N failures)
-- Never chain more than 3 synchronous calls
-- Implement retries with exponential backoff (transient errors only)
-
-### Asynchronous (Events)
-
-| Pattern | When | Watch Out |
-|---------|------|-----------|
-| Pub/Sub | One event, multiple consumers | Message ordering, at-least-once delivery |
-| Command Queue | Exactly-once processing needed | Dead letter queues, poison messages |
-| Event Sourcing | Full audit trail required | Complexity, event schema evolution |
-
-**Rules:**
-- Prefer async communication over sync between services
-- Events are facts (past tense): `OrderPlaced`, `PaymentProcessed`
-- Commands are requests (imperative): `ProcessPayment`, `ShipOrder`
-- Always handle duplicate messages (idempotency)
-
----
-
-## Data Ownership
-
-### The Database-Per-Service Rule
-
-```
-❌ DEATH PENALTY: Shared databases between services
-   Service A → Database ← Service B
-   // One schema change breaks both services
-
-✅ REQUIRED: Each service owns its data
-   Service A → Database A
-   Service B → Database B
-   // Services communicate through APIs or events
-```
-
-### Data Consistency
-
-- **Accept eventual consistency** — strong consistency across services is extremely expensive
-- **Use the Saga pattern** for distributed transactions (choreography or orchestration)
-- **Never use distributed 2PC (two-phase commit)** in production — it doesn't scale
-
----
-
-## Anti-Patterns (Instant Rejection)
-
-| Anti-Pattern | Why It's Dangerous |
-|-------------|-------------------|
-| **Distributed Monolith** | Services that must be deployed together defeat the purpose |
-| **Nano-services** | One function per service creates operational nightmare |
-| **Shared libraries with logic** | Tight coupling through shared code |
-| **Synchronous chains** | A→B→C→D means one failure kills everything |
-| **Shared database** | Schema changes break multiple services |
-| **"We'll figure out observability later"** | You won't find bugs without tracing. Ever. |
-
----
-
-## The Microservices Readiness Checklist
-
-Before splitting ANY module:
-
-- [ ] 2+ trigger conditions met (documented with evidence)
-- [ ] All prerequisites in place (CI/CD, observability, team maturity)
-- [ ] Service boundary defined with clear ownership
-- [ ] API contract defined (OpenAPI, Protobuf, AsyncAPI)
-- [ ] Data ownership clear — no shared tables
-- [ ] Communication pattern chosen (sync vs async)
-- [ ] Failure handling designed (timeouts, circuit breakers, retries)
-- [ ] Monitoring and alerting planned
-- [ ] Rollback strategy defined
-- [ ] Team agrees this is the right decision (not just the architect)
+If the evidence is unclear, document the uncertainty and keep the topology agent-recommended instead of pretending an offline default is correct.

package/.agent-context/rules/naming-conv.md

@@ -1,141 +1,11 @@
-# Naming Conventions — The "No Lazy Names" Standard
+# Naming Boundary
 
-> If your variable name needs a comment to explain it, the name is wrong.
+Use the target language and framework conventions. Do not invent a naming style from this repo.
 
-## Universal Rules (All Languages)
+Reject only these common LLM bad habits:
+- vague names that hide meaning, such as `data`, `result`, `item`, `thing`, `temp`, `handle`, or `process` when a precise domain name exists
+- names that require reading the implementation to understand the value
+- mixed file or directory naming styles inside the same feature without a framework reason
+- booleans, units, and side-effect functions whose names hide what they represent or change
 
-### Variables: Nouns That Tell a Story
-```
-❌ BANNED                    ✅ REQUIRED
-─────────────────────────────────────────────
-d                           durationInSeconds
-data                        userProfilePayload
-res                         httpResponse
-temp                        unsortedItems
-val                         discountPercentage
-info                        orderSummary
-item                        cartLineItem
-list                        activeSubscriptions
-obj                         paymentConfiguration
-```
-
-**Rule:** A variable name must answer "WHAT is this?" without reading surrounding code.
-
-### Functions: Verbs That Declare Intent
-```
-❌ BANNED                    ✅ REQUIRED
-─────────────────────────────────────────────
-process()                   validatePaymentDetails()
-handle()                    routeIncomingWebhook()
-doStuff()                   calculateShippingCost()
-run()                       executeScheduledCleanup()
-getData()                   fetchActiveUsersByRegion()
-check()                     isEligibleForDiscount()
-```
-
-**Rule:** A function name must answer "WHAT does this do?" as a verb phrase. Generic verbs like `process`, `handle`, `manage` are BANNED unless suffixed with a specific noun (e.g., `handlePaymentFailure`).
-
-### Booleans: is/has/can/should Prefix
-```
-❌ BANNED                    ✅ REQUIRED
-─────────────────────────────────────────────
-active                      isActive
-logged                      isLoggedIn
-admin                       hasAdminRole
-edit                        canEditDocument
-visible                     shouldRenderSidebar
-```
-
-**Rule:** Boolean variables MUST use `is`, `has`, `can`, or `should` prefix. No exceptions.
-
-### Constants: SCREAMING_SNAKE for True Constants
-```
-❌ BANNED                    ✅ REQUIRED
-─────────────────────────────────────────────
-maxRetries = 3              MAX_RETRY_COUNT = 3
-timeout = 5000              REQUEST_TIMEOUT_MS = 5000
-apiUrl = "..."              API_BASE_URL = "..."
-```
-
-**Rule:** Use SCREAMING_SNAKE_CASE for compile-time constants and config values. Include the unit in the name when applicable (`_MS`, `_BYTES`, `_COUNT`).
-
-### Single-Letter Variables
-**BANNED.** With exactly ONE exception:
-
-```
-// ALLOWED: Classic loop counter in simple iterations
-for (let i = 0; i < items.length; i++) { ... }
-
-// BANNED: Everything else
-const x = getPrice();        // ❌ What is x?
-const n = users.length;      // ❌ Use userCount
-arr.map(v => v.id);          // ❌ Use user => user.id
-```
-
----
-
-## File & Directory Naming
-
-### Files
-| Type | Convention | Example |
-|------|-----------|---------|
-| Component (React/Vue) | PascalCase | `PaymentForm.tsx` |
-| Module/Service | camelCase or kebab-case | `paymentService.ts` or `payment-service.ts` |
-| Utility | camelCase or kebab-case | `formatCurrency.ts` or `format-currency.ts` |
-| Test | Same as source + `.test`/`.spec` | `paymentService.test.ts` |
-| Type/Interface | PascalCase | `PaymentTypes.ts` |
-| Constant file | SCREAMING_SNAKE or kebab-case | `constants.ts` or `api-endpoints.ts` |
-| Config | kebab-case | `database-config.ts` |
-
-**Rule:** Pick ONE convention per project and enforce it everywhere. Mixing `camelCase` and `kebab-case` in the same project is a code smell.
-
-### Directories
-- Always `kebab-case`: `user-management/`, `payment-processing/`
-- Never PascalCase for directories (except component folders in React convention)
-- No abbreviations: `auth/` → `authentication/` (unless universally understood like `api/`, `db/`)
-
----
-
-## Abbreviation Policy
-
-### Allowed (Universal)
-`id`, `url`, `api`, `db`, `http`, `io`, `ui`, `dto`, `config`, `env`, `auth`, `admin`, `src`, `lib`, `pkg`, `cmd`, `ctx`, `err`, `req`, `res` (in HTTP handler context only)
-
-### Banned
-Everything else. Spell it out:
-```
-❌ usr → ✅ user
-❌ cnt → ✅ count
-❌ mgr → ✅ manager
-❌ btn → ✅ button
-❌ msg → ✅ message
-❌ impl → ✅ implementation
-❌ calc → ✅ calculate
-❌ proc → ✅ process
-```
-
----
-
-## The Naming Decision Tree
-
-```
-Is it a boolean?
-  → Yes → Add is/has/can/should prefix
-  → No ↓
-
-Is it a function?
-  → Yes → Start with a verb (fetch, create, validate, calculate, is, has)
-  → No ↓
-
-Is it a constant?
-  → Yes → SCREAMING_SNAKE_CASE with unit suffix
-  → No ↓
-
-Is it a class/type/interface?
-  → Yes → PascalCase, noun, no prefix (not IUser, not UserInterface)
-  → No ↓
-
-It's a variable
-  → Descriptive noun, camelCase
-  → Must be understandable without context
-```
+Prefer names that explain domain intent, user action, state, and boundary responsibility.