@ryuenn3123/agentic-senior-core 3.0.48 → 3.0.50

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

@@ -56,9 +56,7 @@ If the expressive path needs a new motion, 3D, canvas, scroll, or interaction li
 
 Only downshift ambition after naming the concrete blocker: product fit, content density, measured performance budget, accessibility, device support, package conflict, security risk, or missing runtime capability. A new dependency, package count, or vague performance concern is not a blocker by itself. Pair every downshift with a replacement interaction quality that still changes composition, hierarchy, feedback, or memorability.
 ## Design Flexibility Layer
-`docs/design-intent.json` must separate locked outcomes from flexible expression. The machine contract keeps review invariants stable; it must not freeze exact aesthetic implementation unless repo evidence, accessibility validation, implementation constraints, or explicit user approval locks it.
-
-Record `designFlexibilityPolicy`: lock user goals, runtime constraints, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component-kit theme mapping, signature move implementation, literal anchor artifacts, and spatial metaphors flexible until validated or approved. Semantic roles are required; exact primitives are not automatically locked. Required experience outcomes are separate from candidate implementation moves. Libraries supply behavior, accessibility, primitives, and delivery speed; the project supplies final composition, theme, morphology, and visual language.
+`docs/design-intent.json` must separate locked outcomes from flexible expression. The machine contract keeps review invariants stable; it must not freeze exact aesthetic implementation unless repo evidence, accessibility validation, implementation constraints, or explicit user approval locks it. Record `designFlexibilityPolicy`: lock user goals, runtime constraints, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component-kit theme mapping, signature move implementation, literal anchor artifacts, and spatial metaphors flexible until validated or approved. Semantic roles are required; exact primitives are not automatically locked.
 ## External Inspiration Boundary
 Using outside websites, benchmark apps, galleries, or component examples is useful for constraint discovery, interaction mechanics, and implementation options, but never as a style source to imitate. Extract why a pattern works, then translate it into a current-project rule. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture from a reference unless the user explicitly approves that continuity and it passes product fit.
 
@@ -83,16 +81,17 @@ If rich motion or spatial UI is omitted, record the product, content-density, pe
 If 3D or canvas is used, record product role, interaction model, fallback path, runtime/library choice, loading state, keyboard path, and reduced-motion behavior.
 
 ## Token Derivation Audit
-Before implementation, `docs/design-intent.json` must include top-level `derivedTokenLogic`:
-- `anchorReference`
-- `colorDerivationSource`
-- `spacingDerivationSource`
-- `typographyDerivationSource`
-- `motionDerivationSource`
-- `validationRule`
+Before implementation, `docs/design-intent.json` must include top-level `derivedTokenLogic`: `anchorReference`, `colorDerivationSource`, `spacingDerivationSource`, `typographyDerivationSource`, `motionDerivationSource`, `colorSpace`, `spatialBaseUnit`, `typeScaleMethod`, `motionBudget`, and `validationRule`.
 
 Every semantic token role must trace to `anchorReference`. Exact primitive values stay flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them. If the rationale is "looks good", "common practice", "modern default", or "framework default", derive the token again before UI code.
 
+## Implementation Craft Layer
+Before accepting the design contract, record explicit CSS craft 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.
+
 ## Library Research Protocol
 If web search is available:
 - Verify each new UI-related library against current official docs.

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

@@ -19,19 +19,7 @@ Use this rule for UI, UX, page, screen, component, layout, landing, dashboard, f
 
 ## Required Design Contract
 
-Before UI code, create or refine `docs/DESIGN.md` and `docs/design-intent.json`.
-
-The contract must record:
-- `motionPaletteDecision`
-- `designFlexibilityPolicy`
-- `conceptualAnchor`
-- `derivedTokenLogic`
-- `aiSafeUiAudit`
-- `designExecutionPolicy`
-- `designExecutionHandoff`
-- `reviewRubric`
-- `contextHygiene`
-- `libraryResearchStatus` and `libraryDecisions[]`
+Before UI code, create or refine `docs/DESIGN.md` and `docs/design-intent.json`. The contract must record `motionPaletteDecision`, `designFlexibilityPolicy`, `conceptualAnchor`, `derivedTokenLogic`, `aiSafeUiAudit`, `designExecutionPolicy`, `designExecutionHandoff`, `reviewRubric`, `contextHygiene`, `libraryResearchStatus`, and `libraryDecisions[]`.
 
 ## Anti-Generic UI Gate
 
@@ -66,11 +54,13 @@ 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.
 - Omit rich motion or spatial UI only after naming the product-fit reason and the replacement interaction quality.
 - For new screens or broad redesigns, research the expressive implementation path instead of defaulting to static native CSS. Use native or already-installed tools only when they can still deliver the chosen ambition, or when a concrete blocker is documented. Do not downshift because adding a package feels inconvenient; downshift only for a concrete product-fit, accessibility, security, compatibility, device, maintenance, or measured performance reason.
+- Prefer micro-interactions in 150-300ms, layout transitions in 300-500ms, transform/opacity for high-frequency motion, explicit easing, bounded stagger, and reduced-motion alternatives unless evidence changes the budget.
 - Keep reduced-motion, keyboard, loading, performance, mobile, and non-3D fallbacks explicit.
 - Use component kits or headless primitives for behavior and accessibility when they fit. Replace library-default visual language with project-specific composition, tokens, motion, state treatment, and morphology.
 - Keep design-intent flexible: lock user goals, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component skins, candidate signature moves, and external website inspiration flexible until evidence or approval locks them. Convert references into product-fit rules; do not copy layout, palette, component skin, brand posture, or visual metaphor.
@@ -92,6 +82,7 @@ Responsive quality is not scale-only.
 - Tablet must regroup surfaces instead of shrinking desktop.
 - Desktop may expose more context but must not become interchangeable admin chrome.
 - At least one major surface must change position, grouping, priority, or disclosure strategy between mobile and desktop.
+- Prefer container queries, dynamic viewport units, support-checked selectors, subgrid, popover, or disclosure primitives when they simplify recomposition and fallbacks are clear.
 
 ## Accessibility
 
@@ -100,6 +91,13 @@ Responsive quality is not scale-only.
 - Hard checks include focus visibility, focus appearance, target size, keyboard access, accessible authentication, color-only meaning, and dynamic status/state access.
 - Fix accessibility issues without flattening the UI into generic safe chrome unless no expressive safe option remains.
 
+## CSS Production Hardening
+
+- 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
 
 - Follow the shipped project stack and current repo patterns.

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/lib/cli/project-scaffolder/design-contract/validation.mjs

@@ -27,6 +27,10 @@ export function validateDesignContractCompleteness(designIntentContract) {
       'spacingDerivationSource',
       'typographyDerivationSource',
       'motionDerivationSource',
+      'colorSpace',
+      'spatialBaseUnit',
+      'typeScaleMethod',
+      'motionBudget',
       'validationRule',
     ]) {
       if (!hasNonEmptyString(derivedTokenLogic[requiredFieldName])) {

package/lib/cli/project-scaffolder/design-contract.mjs

@@ -334,6 +334,10 @@ function buildDesignIntentContractObject({
       spacingDerivationSource: 'Explain spacing rhythm, density, and exceptions from anchorReference. Spacing grids are layout math, not decorative background lines.',
       typographyDerivationSource: 'Explain display, body, metadata, and data roles from anchorReference.',
       motionDerivationSource: 'Explain duration, easing, choreography, and reduced-motion from anchorReference.',
+      colorSpace: 'Prefer OKLCH for newly generated CSS tokens when supported; preserve existing design-system token formats and document fallback color space.',
+      spatialBaseUnit: 'Name the base spacing unit, major multiples, density exceptions, and optical exceptions before writing spacing values.',
+      typeScaleMethod: 'Prefer fluid clamp() type scales when supported; name ratio, role contrast, balance/wrap behavior, and numeric typography needs.',
+      motionBudget: 'Name micro, layout, entrance, easing, stagger, and reduced-motion budgets; prefer transform/opacity for high-frequency motion.',
       validationRule: 'Every semantic token role must trace to anchorReference; keep exact primitive values flexible unless locked by repo evidence, accessibility validation, implementation constraints, or explicit user approval.',
     },
     motionPaletteDecision: {

package/lib/cli/project-scaffolder/prompt-builders.mjs

@@ -245,10 +245,14 @@ export function buildDesignBootstrapPrompt({
     'Use reduced-motion fallbacks instead of suppressing motion.',
     '',
     '## Token Derivation Audit',
-    'Before implementation, docs/design-intent.json must include derivedTokenLogic.anchorReference plus colorDerivationSource, spacingDerivationSource, typographyDerivationSource, motionDerivationSource, and validationRule.',
+    'Before implementation, docs/design-intent.json must include derivedTokenLogic.anchorReference plus colorDerivationSource, spacingDerivationSource, typographyDerivationSource, motionDerivationSource, colorSpace, spatialBaseUnit, typeScaleMethod, motionBudget, and validationRule.',
     'Every semantic token role must be explainable from anchorReference. If the rationale is only looks good, common practice, modern default, or framework default, derive the token again before UI code.',
     'Keep exact primitive values flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them.',
     '',
+    '## Implementation Craft Layer',
+    'Record explicit CSS craft decisions before UI code: color space and commitment level, fluid typography method, spacing base unit, motion budget, and the default CSS reflex this project rejects.',
+    'Prefer OKLCH, tinted neutrals, clamp() type scales, transform/opacity motion, and responsive recomposition when supported by the stack; preserve existing design-system tokens and document fallbacks instead of forcing rewrites.',
+    '',
     '## Library Research Protocol',
     'If web search is available, verify every new UI, animation, scroll, 3D, canvas, chart, icon, styling, or primitive library against current official docs and record source URL, fetched date, stable compatible version, purpose, risk, and fallback.',
     'If web search is unavailable or fails, set libraryResearchStatus to pending-verification, record LIBRARY_TO_VERIFY notes, and use native CSS, browser APIs, or already-present project dependencies only when they can preserve the intended ambition until verification is possible.',

package/package.json

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

package/scripts/frontend-usability-audit.mjs

@@ -74,9 +74,12 @@ const REQUIRED_FRONTEND_RULE_SNIPPETS = [
   'Prefer visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity.',
   '## Responsive Mutation',
   'Responsive quality is not scale-only.',
+  'container queries',
   '## Accessibility',
   'WCAG 2.2 AA is the hard floor.',
   'APCA is advisory perceptual tuning only.',
+  '## CSS Production Hardening',
+  'overflow, wrapping, truncation',
   '## Implementation Boundaries',
   'Do not hardcode Zustand, React Query, smart/dumb component doctrine',
 ];
@@ -89,6 +92,7 @@ const REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS = [
   'repoEvidence.designEvidenceSummary',
   'research current official docs',
   'Responsive design means recomposition, not resizing.',
+  'Implementation Craft Layer',
   'agent-chosen visual direction',
   'viewport mutation rules',
   'WCAG 2.2 AA is the hard floor',