@ryuenn3123/agentic-senior-core 3.0.49 → 3.0.50

package/.agent-context/prompts/bootstrap-design.md

@@ -87,7 +87,8 @@ Every semantic token role must trace to `anchorReference`. Exact primitive value
 
 ## Implementation Craft Layer
 Before accepting the design contract, record explicit CSS craft decisions:
-- Color/typography: prefer OKLCH tokens and tinted neutrals for new CSS when supported, preserve existing token formats, name color commitment level, and prefer fluid `clamp()` scales with explicit role contrast, `text-wrap: balance`, and numeric typography decisions.
+- Color: prefer OKLCH tokens and tinted neutrals for new CSS when supported, preserve existing token formats, name color commitment level, derive scales as a perceptual lightness curve (not linear) with semantic role layers (surface, foreground, border, focus, status, data) before primary/secondary/accent, record one accessible text-on-color pair per interactive step, and treat dark mode as a second derived palette with its own lightness curve; record `color-scheme`, prefer `light-dark()` for theme-switch tokens, and record the no-flash and persistence strategy.
+- Typography: prefer fluid `clamp()` scales with explicit role contrast, `text-wrap: balance`, and numeric typography decisions; treat type as a system rather than a font choice, recording one variable-axis decision (`wght`/`wdth`/`opsz` when available), one `font-feature-settings` choice tied to product role (tabular numerals for data, stylistic alternates or `case` for editorial voice), one measure (line-length budget), and an FOUT/FOIT strategy with `font-display` plus metric override when web fonts are loaded.
 - Spatial/motion: name `spatialBaseUnit`, major multiples, optical exceptions, and `motionBudget`; prefer transform/opacity choreography, explicit easing, bounded stagger, and reduced-motion behavior.
 - Implementation anti-attractor: list three default CSS reflexes this task might trigger, reject the most likely one, and choose one distinctive implementation move tied to the product.
 

package/.agent-context/rules/api-docs.md

@@ -29,6 +29,8 @@ Use PRD, SRS, technical design, and ERD as conditional docs, not default boilerp
 - Document the public surface before or alongside implementation.
 - Machine-readable API contracts should use the current project standard. If unresolved, the LLM must recommend a current maintained option from official docs.
 - HTTP APIs should prefer OpenAPI 3.1 when no stronger project standard exists.
+- Choose transport (REST, GraphQL, tRPC, gRPC, SSE, WebSocket) and shape (resource-oriented vs action/command-oriented) from domain evidence, not by habit. When the domain has verbs such as cancel, refund, dispatch, approve, or retry, prefer command endpoints over awkward `PATCH` shoehorns and record at least one alternative transport considered.
+- Treat HTTP as a behavioral contract, not just a shape. Document `ETag` and conditional requests for cacheable reads, `Cache-Control` and `Vary` when shared caches apply, rate-limit headers (`RateLimit-*` or `X-RateLimit-*`) with `Retry-After` when rate limiting exists, and require an `Idempotency-Key` request header on unsafe non-idempotent mutations.
 - List endpoints must document pagination, limits, filtering, sorting, and empty-state behavior.
 - Sensitive mutation endpoints must document idempotency behavior, retry safety, duplicate-submit handling, and any required idempotency key or request fingerprint.
 - Public error contracts must document stable machine-readable codes and any RFC 9457 Problem Details-style fields the project exposes, including safe trace or correlation identifiers when present.

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

@@ -11,6 +11,7 @@ These principles are mandatory for backend and shared core modules.
 - Readability over brevity.
 - Keep transport, application, domain, and infrastructure concerns separated.
 - Favor explicit module boundaries over hidden cross-layer shortcuts.
+- Health endpoints distinguish liveness (the process is alive), readiness (the process can serve traffic), and startup (initialization complete) where the runtime supports it. A `200 OK` that does not check critical dependencies is not a readiness signal.
 
 ## Complexity Budget (Mandatory)
 
@@ -21,6 +22,7 @@ Prefer the smallest clear implementation that fully preserves behavior, safety,
 - Prefer direct logic over extra wrappers, layers, classes, config, or state when the abstraction does not reduce real complexity.
 - Keep validation, error handling, fallback paths, accessibility, tests, security boundaries, and observability when they protect real behavior.
 - Run a final simplification pass before completion.
+- Run a domain-fit pass on public contracts before completion: if endpoint names, payload fields, error codes, table names, or event types could be renamed to another domain without changing shape, the contract is too generic; revise to express the actual domain verbs and invariants. This is the backend equivalent of the design rename test.
 - Do not optimize for line count alone.
 - Do not replace clear code with clever, dense, or surprising code.
 - Do not remove safeguards just because the happy path works.

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

@@ -17,6 +17,8 @@ Backend data access rules:
 - Define maximum page size, payload size, and export limits so list responses cannot exhaust memory or connection pools.
 - Mutations that write more than one table, aggregate, queue, or external consistency boundary must run inside a transaction or document the compensating recovery path.
 - Repository and data-access layers own persistence mechanics. They must not hide business policy that belongs in application or domain logic.
+- Index design follows read patterns, not column lists. Prefer composite indexes with selectivity-correct column order (equality before range), partial indexes for soft-delete or status-filtered tables, and covering indexes when a hot read can be satisfied without a heap fetch. Record the read pattern that justifies each non-trivial index.
+- Record explicit decisions for delete semantics (hard delete, soft delete, append-only audit), tenant isolation (none, row-level with `tenant_id` plus row-level security, schema-per-tenant), and normalize-vs-denormalize trade-off for read-heavy or sparse data. Default to the simplest fit, but make the choice explicit in data docs rather than letting it become a side effect of the first migration.
 - Cross-domain persistence must respect ownership boundaries. Independent services must not share database tables as an integration contract; modular monoliths may share one database only when module ownership and access paths stay explicit.
 
 Docs must record entity ownership, relationships, constraints, data lifecycle, migration risk, and assumptions to validate.

package/.agent-context/rules/error-handling.md

@@ -16,5 +16,7 @@ Backend API error rules:
 - Domain and validation errors should keep machine-readable codes so tests, clients, and operators can distinguish expected failures from defects.
 - API boundary errors should include a safe correlation or trace identifier when observability exists, while protected logs keep the internal exception, actor, target, and trace context.
 - Distributed systems should preserve trace context across ingress and egress using the project's tracing standard, such as W3C Trace Context or OpenTelemetry propagation.
+- Prefer structured logging (key/value or JSON) over free-text strings, record at least one business metric per non-trivial operation alongside system metrics, and propagate correlation/trace IDs across async, queue, and worker boundaries.
+- Distinguish error reporting from error recovery. For calls to unreliable upstreams, record the recovery strategy: retry with backoff and jitter, circuit-breaker thresholds and reset behavior, fallback path (cached value, default, degraded mode), and partial-failure semantics for batch operations (per-item success/failure rather than all-or-nothing). "Catch and log" is reporting, not recovery.
 
 At boundaries, validate early, return safe user-facing errors, and keep machine-readable error context for operators and callers.

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

@@ -54,6 +54,7 @@ If the user gives no current-task visual research or reference:
 - Product categories are heuristics, not style presets.
 - Choose motion density from task, content density, brand intent, device budget, performance, and accessibility.
 - Map states before coding: default, hover, focus-visible, active, disabled, loading, empty, error, success, transition.
+- Distinguish motion (visual continuity between states) from interaction design (state machines, focus transfer on route/modal/error transitions, optimistic updates where safe, skeleton shapes that match real content, `aria-live` for status, keyboard paths, scroll-driven progressive disclosure). Record at least one interaction-design decision per major flow alongside motion choices.
 - Prefer visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity.
 - Do not default to dark slate, cream/beige/tan, purple-blue gradients, monochrome palettes, cyber-neon terminals, or uniform card surfaces without product evidence.
 - Treat motion, 3D, WebGL, canvas, scroll choreography, and animation libraries as first-class options.
@@ -94,6 +95,7 @@ Responsive quality is not scale-only.
 
 - Plan overflow, wrapping, truncation, empty, loading, error, and extreme-content behavior before declaring a layout complete.
 - Prefer `min()`, `max()`, `clamp()`, stable aspect ratios, container-relative sizing, OKLCH, and tinted neutrals for new tokens when supported; preserve existing design-system tokens.
+- Prefer composition primitives that match content meaning: named `grid-template-areas` for editorial regions, subgrid for nested alignment across siblings, container queries for component-level responsiveness independent of viewport, and explicit stacking context (`isolation: isolate`) when overlap or z-depth carries meaning. Do not default to flex column when content has structure that grid expresses better.
 - Treat recursive card nesting, uniform radius everywhere, shadow on every surface, arbitrary spacing, gray text on saturated color, and library-default skins as drift signals requiring product rationale.
 
 ## Implementation Boundaries

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

@@ -9,3 +9,5 @@ Reject only these common LLM bad habits:
 - booleans, units, and side-effect functions whose names hide what they represent or change
 
 Prefer names that explain domain intent, user action, state, and boundary responsibility.
+
+Inline comments must explain why, not what. Non-obvious choices (retry strategy, index column order, denormalized field, intentional swallow with named recovery, magic constant tied to an external system) deserve a one-line rationale near the code; comments that paraphrase the code are noise.

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

@@ -12,3 +12,5 @@ Hard rejections:
 - caches without invalidation, expiry, ownership, and staleness trade-offs
 
 When performance matters, measure the real bottleneck, change the smallest useful thing, and verify the result. Do not downshift product quality, UI ambition, or library fit from performance fear alone; name the concrete budget, bottleneck, device limit, or runtime evidence.
+
+Caching is a tier decision before a technology decision. Prefer browser, CDN, or HTTP cache layers when data is shared and public; prefer in-process caches for hot per-instance data; reach for distributed caches such as Redis or Memcached only when shared mutable state across instances is the actual requirement. Record cache-aside, write-through, or write-behind shape, invalidation strategy, and stampede prevention (request coalescing or stale-while-revalidate) when the cache fronts an expensive backend.

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

@@ -14,6 +14,7 @@ Hard rules:
 - retrieve secrets through environment, runtime secret injection, or the project's secret manager; do not store static secrets in source or plaintext config
 - keep `.env` and local secret files covered by `.gitignore`; commit only safe examples such as `.env.example`
 - treat transport encryption, secure cookies, and trusted proxy boundaries as deployment assumptions that must be documented when sensitive traffic is involved
+- when a public surface exists, record explicit decisions for: CORS allow-list (not `*` for credentialed requests), security headers (CSP, HSTS, `X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`), JWT pitfalls (algorithm pinning, expiration, refresh rotation, storage location), webhook signature verification with timing-safe compare, SSRF defense (egress allow-list or URL validation) when the server fetches user-supplied URLs, and per-resource authorization (not role-only) when records have owners
 
 Zero-trust API input rules:
 - Treat body, query, params, headers, cookies, uploaded files, webhook payloads, and background job payloads as untrusted until validated.

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

@@ -15,6 +15,7 @@ Backend/API test rules:
 - Event or worker changes must test retry, duplicate-message handling, dead-letter or recovery behavior, and outbox relay semantics when those paths exist.
 - Distributed consistency changes must test the local transaction, publish/retry behavior, and compensating action or recovery path rather than only the happy path.
 - Tests should make the API contract obvious from the fixture names, inputs, and expected response shape.
+- Tests must exercise the failure paths the code claims to handle, not only the happy path. Prefer property-based or generated-input tests for invariants (validation, ordering, idempotency), explicit failure-injection tests for retry and recovery code, and contract tests at service boundaries when consumer and producer ownership is split.
 
 Do not test framework internals, third-party library behavior, private implementation trivia, or snapshots that only freeze noise.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.49",
+  "version": "3.0.50",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {