@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.0

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

@@ -1,47 +1,70 @@
+---
+id_prefix: DOCK
+domain: docker-runtime
+priority: high
+scope: infra
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - docker-runtime
+  - dock
+  - docker
+  - runtime
+---
+
 # Docker Runtime Strategy (Dynamic Generation Required)
 
 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.
-- 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.
-- 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.
-- 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.
-- Development lane priorities: fast rebuild, hot reload support, debugger-friendly startup, local volume strategy.
-- Production lane priorities: minimal image size, reproducible build, non-root runtime, strict startup command.
-
-## 3. Selection Means Asset Materialization
-- If Docker is selected for development, create or refine `.dockerignore`, development Dockerfile stage(s), `compose.yaml`, and a runbook before claiming the setup is complete.
-- If Docker is selected for production, create or refine production Dockerfile stage(s), `compose.prod.yaml` or a documented production Compose override, health checks or startup checks, exposed ports, and a deployment runbook before claiming the setup is complete.
-- If Docker is selected for both lanes, keep development and production assets separate enough that hot reload, bind mounts, debug tooling, and production runtime hardening cannot blur into one unsafe path.
-- If the user asks to author files without commands, write the assets and documented commands, but do not execute Docker build, Compose, or registry commands.
-
-## 4. Security and Supply Chain
-- Use minimal trusted base images with explicit versions.
-- Use multi-stage builds for production images when possible.
-- Avoid baking secrets into image layers.
-- Keep runtime image free from build-only tooling.
-- 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.
-
-## 5. Operational Clarity
-- Docker instructions must document expected entrypoint and exposed ports.
-- Local development command and production deployment command must be explicit.
-- If Docker is not selected for the project, do not force containerization tasks.
-- If Compose is used, document which file is the primary entrypoint, which services are dev-only versus production-facing, and why the chosen layout matches the current Docker docs rather than a legacy blog pattern.
-
-## 6. Review Requirements
-- Verify the generated Docker workflow matches selected runtime environment (Linux/WSL, Windows, macOS).
-- Verify development and production instructions are not mixed into one unsafe image path.
-- Ensure API and service health checks are compatible with container startup behavior.
-- When Docker choices depend on official docs or release behavior, cite the Docker source and verification date in the generated docs or explanation so the next update can refresh them safely.
+## DOCK-001: Latest Official Docker Guidance First
+
+1. Before generating or changing Dockerfiles, Compose files, or container runbooks, verify the latest official Docker documentation first.
+2. 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/).
+3. 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.
+4. 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.
+5. 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.
+
+## DOCK-002: Dynamic Generation Only
+
+1. Do not copy generic Docker templates blindly.
+2. Generate Docker assets based on actual stack, package manager, and runtime dependencies in the repository.
+3. Re-evaluate Docker instructions when dependencies, build tools, or runtime assumptions change.
+4. 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.
+
+## DOCK-003: Separate Development and Production Lanes
+
+1. Development lane and production lane are separate concerns.
+2. Development lane priorities: fast rebuild, hot reload support, debugger-friendly startup, local volume strategy.
+3. Production lane priorities: minimal image size, reproducible build, non-root runtime, strict startup command.
+
+## DOCK-004: Selection Means Asset Materialization
+
+1. If Docker is selected for development, create or refine `.dockerignore`, development Dockerfile stage(s), `compose.yaml`, and a runbook before claiming the setup is complete.
+2. If Docker is selected for production, create or refine production Dockerfile stage(s), `compose.prod.yaml` or a documented production Compose override, health checks or startup checks, exposed ports, and a deployment runbook before claiming the setup is complete.
+3. If Docker is selected for both lanes, keep development and production assets separate enough that hot reload, bind mounts, debug tooling, and production runtime hardening cannot blur into one unsafe path.
+4. If the user asks to author files without commands, write the assets and documented commands, but do not execute Docker build, Compose, or registry commands.
+
+## DOCK-005: Security and Supply Chain
+
+1. Use minimal trusted base images with explicit versions.
+2. Use multi-stage builds for production images when possible.
+3. Avoid baking secrets into image layers.
+4. Keep runtime image free from build-only tooling.
+5. Use fresh base-image validation with `docker build --pull` and use `--no-cache` when a clean dependency refresh is required.
+6. Keep a `.dockerignore` strategy in mind so build contexts stay small and do not leak unnecessary files into the image.
+
+## DOCK-006: Operational Clarity
+
+1. Docker instructions must document expected entrypoint and exposed ports.
+2. Local development command and production deployment command must be explicit.
+3. If Docker is not selected for the project, do not force containerization tasks.
+4. If Compose is used, document which file is the primary entrypoint, which services are dev-only versus production-facing, and why the chosen layout matches the current Docker docs rather than a legacy blog pattern.
+
+## DOCK-007: Review Requirements
+
+1. Verify the generated Docker workflow matches selected runtime environment (Linux/WSL, Windows, macOS).
+2. Verify development and production instructions are not mixed into one unsafe image path.
+3. Ensure API and service health checks are compatible with container startup behavior.
+4. When Docker choices depend on official docs or release behavior, cite the Docker source and verification date in the generated docs or explanation so the next update can refresh them safely.

package/.agent-context/rules/efficiency-vs-hype.md

@@ -1,24 +1,45 @@
-# Dependency and Tooling Boundary
+---
+id_prefix: DEP
+domain: efficiency-vs-hype
+priority: medium
+scope: all-tasks
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - efficiency-vs-hype
+  - dep
+  - dependency
+  - latest-compatible-first
+---
 
-## Latest-Compatible-First Rule
+# Dependency and Tooling Boundary
 
-The LLM may choose modern libraries and tooling when they fit the project. This rule does not prefer "no library", "always add a library", or any fixed dependency set.
+## DEP-001: Latest-Compatible-First Rule
 
-New dependencies are allowed when they create a better practical tradeoff than custom implementation. The decision should be based on whether the dependency meaningfully improves efficiency, shortens delivery time, improves correctness, reduces maintenance burden, unlocks a stronger user experience, or avoids unnecessary in-house code.
+1. The LLM may choose modern libraries and tooling when they fit the project.
+2. This rule does not prefer "no library", "always add a library", or any fixed dependency set.
+3. New dependencies are allowed when they create a better practical tradeoff than custom implementation.
+4. The decision should be based on whether the dependency meaningfully improves efficiency, shortens delivery time, improves correctness, reduces maintenance burden, unlocks a stronger user experience, or avoids unnecessary in-house code.
+5. Do not treat dependency avoidance as an engineering virtue by itself.
+6. A small, maintained, well-scoped library can be the simpler and safer choice than custom code, especially for accessibility primitives, animation, gestures, data visualization, parsing, protocol handling, security-sensitive helpers, or browser/runtime capabilities with tricky edge cases.
 
-Do not treat dependency avoidance as an engineering virtue by itself. A small, maintained, well-scoped library can be the simpler and safer choice than custom code, especially for accessibility primitives, animation, gestures, data visualization, parsing, protocol handling, security-sensitive helpers, or browser/runtime capabilities with tricky edge cases.
+## DEP-002: Before adding or recommending a dependency
 
-Before adding or recommending a dependency:
-- check current official docs, release notes, and setup guidance when the ecosystem decision matters
-- choose the latest stable compatible dependency version unless a project constraint blocks it
-- use the official scaffolder or setup command when it creates the current supported project shape
-- do not hand-assemble fresh framework projects by habit when the official setup flow gives safer current defaults; document the reason when manual assembly is better
-- Only step down to an older dependency version after documenting the exact compatibility, runtime, platform, or ecosystem reason.
-- explain why the dependency is a better tradeoff than local implementation for the current task
-- avoid packages that are stale, thinly maintained, too heavy for the job, or added only because they are popular
-- keep dependency boundaries replaceable when the library would spread through many files
-- do not reject a dependency only because it adds a package; reject it only when the project-fit, security, maintenance, compatibility, bundle/runtime, or ownership tradeoff is worse than the alternative
+1. check current official docs, release notes, and setup guidance when the ecosystem decision matters
+2. choose the latest stable compatible dependency version unless a project constraint blocks it
+3. use the official scaffolder or setup command when it creates the current supported project shape
+4. do not hand-assemble fresh framework projects by habit when the official setup flow gives safer current defaults; document the reason when manual assembly is better
+5. Only step down to an older dependency version after documenting the exact compatibility, runtime, platform, or ecosystem reason.
+6. explain why the dependency is a better tradeoff than local implementation for the current task
+7. avoid packages that are stale, thinly maintained, too heavy for the job, or added only because they are popular
+8. keep dependency boundaries replaceable when the library would spread through many files
+9. do not reject a dependency only because it adds a package; reject it only when the project-fit, security, maintenance, compatibility, bundle/runtime, or ownership tradeoff is worse than the alternative
 
-Reject offline dependency decisions, outdated tutorial versions, trend choices, dependency avoidance choices, and performance-fear choices that are not grounded in the current repo, brief, and delivery tradeoffs.
+## DEP-003: Framework and offline decision boundaries
 
-Reject framework autopilot, not frameworks. Next.js, Vite, Astro, React Router, SvelteKit, Laravel, plain HTML, and other runtimes are candidates, not defaults or forbidden choices. If the user did not constrain the stack, compare at least the strongest fit and one plausible alternative before implementation, then choose the technology that removes bottlenecks for this project.
+1. Reject offline dependency decisions, outdated tutorial versions, trend choices, dependency avoidance choices, and performance-fear choices that are not grounded in the current repo, brief, and delivery tradeoffs.
+2. Reject framework autopilot, not frameworks.
+3. Next.js, Vite, Astro, React Router, SvelteKit, Laravel, plain HTML, and other runtimes are candidates, not defaults or forbidden choices.
+4. If the user did not constrain the stack, compare at least the strongest fit and one plausible alternative before implementation, then choose the technology that removes bottlenecks for this project.

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

@@ -1,22 +1,41 @@
+---
+id_prefix: ERR
+domain: error-handling
+priority: high
+scope: all-tasks
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - error-handling
+  - err
+  - error
+  - handling
+  - boundary
+  - reject
+---
+
 # Error Handling Boundary
 
 Use the target language and framework's normal error model. Do not invent a custom exception architecture from this repo.
 
-Reject these failure patterns:
-- swallowed errors
-- generic errors that erase the domain cause
-- client-facing leaks of stack traces, secrets, SQL, infrastructure details, or provider internals
-- retries without transient-failure evidence, limits, backoff, and a clear final outcome
-- logs that say only "something failed" without action, target, actor, or trace context
+## ERR-001: Reject these failure patterns
+
+1. swallowed errors
+2. generic errors that erase the domain cause
+3. client-facing leaks of stack traces, secrets, SQL, infrastructure details, or provider internals
+4. retries without transient-failure evidence, limits, backoff, and a clear final outcome
+5. logs that say only "something failed" without action, target, actor, or trace context
 
-Backend API error rules:
-- Use the framework's normal centralized error boundary or middleware for HTTP/API responses.
-- Do not return raw exception messages, stack traces, SQL, provider payloads, file paths, secrets, or infrastructure details to callers.
-- Public API errors must use a stable JSON shape with at least `code` and `message`; include `details` only when the data is safe, documented, and useful to the caller. HTTP APIs may use an RFC 9457 Problem Details-style shape when it fits the project contract.
-- 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.
+## ERR-002: Backend API error rules
 
-At boundaries, validate early, return safe user-facing errors, and keep machine-readable error context for operators and callers.
+1. Use the framework's normal centralized error boundary or middleware for HTTP/API responses.
+2. Do not return raw exception messages, stack traces, SQL, provider payloads, file paths, secrets, or infrastructure details to callers.
+3. Public API errors must use a stable JSON shape with at least `code` and `message`; include `details` only when the data is safe, documented, and useful to the caller. HTTP APIs may use an RFC 9457 Problem Details-style shape when it fits the project contract.
+4. Domain and validation errors should keep machine-readable codes so tests, clients, and operators can distinguish expected failures from defects.
+5. 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.
+6. Distributed systems should preserve trace context across ingress and egress using the project's tracing standard, such as W3C Trace Context or OpenTelemetry propagation.
+7. 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.
+8. 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.
+9. At boundaries, validate early, return safe user-facing errors, and keep machine-readable error context for operators and callers.

package/.agent-context/rules/event-driven.md

@@ -1,25 +1,42 @@
+---
+id_prefix: EVT
+domain: event-driven
+priority: medium
+scope: backend
+applies_to:
+  - backend
+  - fullstack
+keywords:
+  - event-driven
+  - evt
+  - events
+  - consumers
+  - outbox
+  - consistency
+---
+
 # Event Boundary
 
 Do not add event-driven architecture because it sounds modern. Use it only when the product or repo shows a real async boundary.
 
-Use events when:
-- multiple independent consumers must react to the same fact
-- synchronous coupling would harm reliability, latency, or ownership
-- audit history, fan-out, or eventual consistency is a real requirement
-- the team can operate retries, monitoring, and failure recovery
+## EVT-001: Event Boundary and Hard Delivery Rules
 
-Reject events when a direct call, database transaction, or simple module boundary is enough.
+1. Use events when multiple independent consumers must react to the same fact.
+2. Use events when synchronous coupling would harm reliability, latency, or ownership.
+3. Use events when audit history, fan-out, or eventual consistency is a real requirement.
+4. Use events only when the team can operate retries, monitoring, and failure recovery.
+5. Reject events when a direct call, database transaction, or simple module boundary is enough.
+6. Events describe facts that already happened.
+7. Payloads are versioned, typed, and documented.
+8. Producers do not know consumer internals.
+9. Consumers are idempotent.
+10. Retries are bounded and dead-letter or recovery behavior is defined.
+11. Transactional publishing uses an outbox or equivalent safety pattern when data consistency matters.
+12. Dual-write flows that update local state and publish a message must use a transactional outbox or document an equivalent atomicity and replay strategy.
 
-Hard rules:
-- events describe facts that already happened
-- payloads are versioned, typed, and documented
-- producers do not know consumer internals
-- consumers are idempotent
-- retries are bounded and dead-letter or recovery behavior is defined
-- transactional publishing uses an outbox or equivalent safety pattern when data consistency matters
-- dual-write flows that update local state and publish a message must use a transactional outbox or document an equivalent atomicity and replay strategy
-- distributed transactions and two-phase commit are not the default recovery model; prefer local transactions plus saga, choreography, orchestration, or explicit compensating actions when consistency crosses service boundaries
-- message handlers must record processed message identifiers or use another duplicate-detection strategy when the delivery model can retry or redeliver
-- event catalogs or docs identify producer, consumers, ownership, and schema evolution rules
+## EVT-002: Event Recovery and Catalogs
 
-If event tooling is unresolved, the LLM must recommend a current project-fit broker or managed service from official docs before implementation.
+1. Distributed transactions and two-phase commit are not the default recovery model; prefer local transactions plus saga, choreography, orchestration, or explicit compensating actions when consistency crosses service boundaries.
+2. Message handlers must record processed message identifiers or use another duplicate-detection strategy when the delivery model can retry or redeliver.
+3. Event catalogs or docs identify producer, consumers, ownership, and schema evolution rules.
+4. If event tooling is unresolved, recommend a current project-fit broker or managed service from official docs before implementation.

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

@@ -1,107 +1,134 @@
+---
+id_prefix: FE
+domain: frontend-architecture
+priority: high
+scope: ui
+applies_to:
+  - frontend
+  - fullstack
+keywords:
+  - frontend-architecture
+  - fe
+  - ui
+  - design
+  - interaction
+  - boundaries
+---
+
 # Frontend Design and Interaction Boundaries
 
 Load this rule for UI-facing work. Keep the loaded surface small.
 
-## Activation
+## FE-001: Activation
+
+1. Use this rule for UI, UX, page, screen, component, layout, landing, dashboard, form, onboarding, animation, interaction, redesign, visual refresh, responsive fix, hierarchy fix, and frontend deliverables inside fullstack or backend work.
+
+## FE-002: Authority
 
-Use this rule for UI, UX, page, screen, component, layout, landing, dashboard, form, onboarding, animation, interaction, redesign, visual refresh, responsive fix, hierarchy fix, and frontend deliverables inside fullstack or backend work.
+1. Use current repo evidence, the active brief, and current project docs as valid style context.
+2. Treat `.agent-context/` as design governance authority.
+3. Treat `README.md` as public and developer overview, setup, usage, and user-facing context only when design or architecture rules conflict.
+4. Do not choose final style, framework, palette, typography, layout paradigm, or animation library offline.
+5. Research current official docs before adding a new UI, animation, scroll, 3D, canvas, charting, icon, styling, or primitive library.
+6. Dynamic UI Foundation: do not hardcode shadcn/ui, Tailwind-only, native-only, or any component library as the universal answer, and do not avoid them out of guardrail fear when they fit. Tailwind-first is valid when the stack, token model, and team workflow support it; pure Tailwind, vanilla CSS, shadcn/ui, or any kit is not neutral by itself. Modern primitives, motion/canvas/WebGL helpers, charting libraries, and styling tools are valid when product evidence, accessibility, runtime constraints, and official docs support them.
+7. For fresh projects, prefer official framework scaffolders or setup commands when official docs show they produce the current supported shape. Build files manually only when approved architecture, repo constraints, or learning/prototype scope makes that better.
+8. Keep design continuity opt-in. Repo evidence outranks memory residue.
 
-## Authority
+## FE-003: Required Design Contract
 
-- Use current repo evidence, the active brief, and current project docs as valid style context.
-- Treat `.agent-context/` as design governance authority.
-- Treat `README.md` as public and developer overview, setup, usage, and user-facing context only when design or architecture rules conflict.
-- Do not choose final style, framework, palette, typography, layout paradigm, or animation library offline.
-- Research current official docs before adding a new UI, animation, scroll, 3D, canvas, charting, icon, styling, or primitive library.
-- Dynamic UI Foundation: do not hardcode shadcn/ui, Tailwind-only, native-only, or any component library as the universal answer, and do not avoid them out of guardrail fear when they fit. Tailwind-first is valid when the stack, token model, and team workflow support it; pure Tailwind, vanilla CSS, shadcn/ui, or any kit is not neutral by itself. Modern primitives, motion/canvas/WebGL helpers, charting libraries, and styling tools are valid when product evidence, accessibility, runtime constraints, and official docs support them.
-- For fresh projects, prefer official framework scaffolders or setup commands when official docs show they produce the current supported shape. Build files manually only when approved architecture, repo constraints, or learning/prototype scope makes that better.
-- Keep design continuity opt-in. Repo evidence outranks memory residue.
+1. Before UI code, create or refine `docs/DESIGN.md` and `docs/design-intent.json`.
+2. The contract must record `motionPaletteDecision`, `designFlexibilityPolicy`, `conceptualAnchor`, `derivedTokenLogic`, `aiSafeUiAudit`, `designExecutionPolicy`, `designExecutionHandoff`, `reviewRubric`, `contextHygiene`, `libraryResearchStatus`, and `libraryDecisions[]`.
 
-## Required Design Contract
+## FE-004: Anti-Generic UI Gate
 
-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[]`.
+1. Do not ship interchangeable dashboard chrome, balanced card grids, centered marketing shells, generic component-kit surfaces, generic abstract logos, or nonfunctional background decoration unless the product earns them.
+2. For new screens or broad redesigns, make at least three at-a-glance product-specific signals visible. Signals may be data treatment, iconography, state language, motion behavior, spatial structure, typography, material logic, or color behavior.
+3. Use the rename test: if the UI can be renamed to another product category without changing composition, palette, iconography, and motion language, revise before implementation is considered complete.
+4. Use the old-design regression test for broad redesigns: if the UI reads as the previous design with fewer details, removed animation, simplified sections, or a new palette on the same composition, revise before implementation is considered complete.
 
-## Anti-Generic UI Gate
+## FE-005: Dynamic Anchor Gate
 
-Do not ship interchangeable dashboard chrome, balanced card grids, centered marketing shells, generic component-kit surfaces, generic abstract logos, or nonfunctional background decoration unless the product earns them.
+1. If the user gives no current-task visual research or reference, do not count old UI, existing design docs, or scaffold seeds as research.
+2. Choose one high-variance non-software conceptual anchor before UI code.
+3. Internally reject the safest dashboard, portal, card-grid, admin-shell, or minimalist-web-app mental model.
+4. Do not let the fallback anchor become a generic place metaphor. Avoid room, darkroom, counting room, control room, war room, studio, lab, cockpit, and command center unless the product actually depends on that place model; prefer product-specific artifacts, workflows, custody chains, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms over "where the UI lives".
+5. Record one real-world anchor reference, one signature motion behavior, and one typographic decision with role contrast.
+6. Derive typography, spacing, morphology, motion, and responsive recomposition from that anchor.
+7. Translate the anchor into workflow, hierarchy, density, typography, state behavior, and interaction before using literal artifacts. Do not turn anchor artifacts into required chrome, wallpaper, decorative props, or component-kit theme objects without a named product function.
+8. Reject anchors described only by generic quality words such as modern, clean, premium, expressive, minimal, or bold.
 
-For new screens or broad redesigns, make at least three at-a-glance product-specific signals visible. Signals may be data treatment, iconography, state language, motion behavior, spatial structure, typography, material logic, or color behavior.
+## FE-006: Motion, Palette, and 3D
 
-Use the rename test: if the UI can be renamed to another product category without changing composition, palette, iconography, and motion language, revise before implementation is considered complete.
+1. Product categories are heuristics, not style presets.
+2. Choose motion density from task, content density, brand intent, device budget, performance, and accessibility.
+3. Map states before coding: default, hover, focus-visible, active, disabled, loading, empty, error, success, transition.
+4. 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.
+5. Prefer visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity.
+6. Do not default to dark slate, cream/beige/tan, purple-blue gradients, monochrome palettes, cyber-neon terminals, or uniform card surfaces without product evidence.
+7. Treat motion, 3D, WebGL, canvas, scroll choreography, and animation libraries as first-class options.
 
-Use the old-design regression test for broad redesigns: if the UI reads as the previous design with fewer details, removed animation, simplified sections, or a new palette on the same composition, revise before implementation is considered complete.
+## FE-007: Zero-Based Redesign
 
-Background lines, grids, scanlines, noise, glows, blobs, abstract logos, calibration marks, and decorative geometry are invalid as wallpaper. Do not use grid or line backgrounds as first-output filler. Use them only for a named product function such as alignment, crop guidance, map/route orientation, timeline reading, measurement, status, or motion continuity.
+1. If the user asks for a redesign from zero, treat existing UI as behavioral/content evidence only.
+2. Discard prior palette, typography, hero composition, navigation placement, component morphology, motion signature, and image framing unless the user requests continuity.
+3. Rewrite or materially update both design docs before coding.
+4. Change primary composition, content hierarchy, interaction model, and responsive information architecture.
+5. Reject palette swaps, dark-mode flips, and restyled heroes.
+6. Reject implementations that remove animation, media, depth, or interaction density merely to reduce complexity when the request calls for a more distinctive experience.
 
-Measurement, calibration, crop, map, route, and inspection marks are task-bound overlays or control affordances. They must not become the page background, hero backdrop, or default visual texture. When a conceptual anchor and a forbidden visual motif conflict, the forbidden motif wins; translate the anchor into layout, hierarchy, density, typography, state behavior, materials, and interaction instead of literal decorative texture.
+## FE-008: Responsive Mutation
 
-Production UI must read as ship-ready: no visible testing, demo, sample, placeholder, lorem, TODO, coming soon, or scaffold labels unless they are intentional product states. User-facing workflows need an operable UI path; terminal-only core flows are valid only for CLI, developer-tool, or runbook products.
+1. Responsive quality is not scale-only.
+2. Mobile must prioritize the first decisive action.
+3. Tablet must regroup surfaces instead of shrinking desktop.
+4. Desktop may expose more context but must not become interchangeable admin chrome (see [REF:FE-004]).
+5. At least one major surface must change position, grouping, priority, or disclosure strategy between mobile and desktop.
+6. Prefer container queries, dynamic viewport units, support-checked selectors, subgrid, popover, or disclosure primitives when they simplify recomposition and fallbacks are clear.
 
-## Dynamic Anchor Gate
+## FE-009: Accessibility
 
-If the user gives no current-task visual research or reference:
-- Do not count old UI, existing design docs, or scaffold seeds as research.
-- Choose one high-variance non-software conceptual anchor before UI code.
-- Internally reject the safest dashboard, portal, card-grid, admin-shell, or minimalist-web-app mental model.
-- Do not let the fallback anchor become a generic place metaphor. Avoid room, darkroom, counting room, control room, war room, studio, lab, cockpit, and command center unless the product actually depends on that place model; prefer product-specific artifacts, workflows, custody chains, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms over "where the UI lives".
-- Record one real-world anchor reference, one signature motion behavior, and one typographic decision with role contrast.
-- Derive typography, spacing, morphology, motion, and responsive recomposition from that anchor.
-- Translate the anchor into workflow, hierarchy, density, typography, state behavior, and interaction before using literal artifacts. Do not turn anchor artifacts into required chrome, wallpaper, decorative props, or component-kit theme objects without a named product function.
-- Reject anchors described only by generic quality words such as modern, clean, premium, expressive, minimal, or bold.
+1. WCAG 2.2 AA is the hard floor.
+2. APCA is advisory perceptual tuning only.
+3. Hard checks include focus visibility, focus appearance, target size, keyboard access, accessible authentication, color-only meaning, and dynamic status/state access.
+4. Fix accessibility issues without flattening the UI into generic safe chrome unless no expressive safe option remains (see [REF:FE-004]).
 
-## Motion, Palette, and 3D
+## FE-010: CSS Production Hardening
 
-- 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.
-## Zero-Based Redesign
+1. Plan overflow, wrapping, truncation, empty, loading, error, and extreme-content behavior before declaring a layout complete.
+2. Prefer `min()`, `max()`, `clamp()`, stable aspect ratios, container-relative sizing, OKLCH, and tinted neutrals for new tokens when supported; preserve existing design-system tokens.
+3. 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.
+4. 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.
 
-If the user asks for a redesign from zero:
-- Treat existing UI as behavioral/content evidence only.
-- Discard prior palette, typography, hero composition, navigation placement, component morphology, motion signature, and image framing unless the user requests continuity.
-- Rewrite or materially update both design docs before coding.
-- Change primary composition, content hierarchy, interaction model, and responsive information architecture.
-- Reject palette swaps, dark-mode flips, and restyled heroes.
-- Reject implementations that remove animation, media, depth, or interaction density merely to reduce complexity when the request calls for a more distinctive experience.
+## FE-011: Implementation Boundaries
 
-## Responsive Mutation
+1. Follow the shipped project stack and current repo patterns.
+2. Do not hardcode Zustand, React Query, smart/dumb component doctrine, or framework-specific architecture as universal design law.
+3. Keep structure feature-oriented when it improves maintainability.
+4. Keep component states recognizable across hover, focus, loading, success, empty, and error.
+5. Do not let repeated surfaces share one visual treatment by habit; repetition needs a product reason.
 
-Responsive quality is not scale-only.
+## FE-013: Background and Wallpaper Discipline
 
-- Mobile must prioritize the first decisive action.
-- 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.
+1. Background lines, grids, scanlines, noise, glows, blobs, abstract logos, calibration marks, and decorative geometry are invalid as wallpaper.
+2. Do not use grid or line backgrounds as first-output filler.
+3. Use them only for a named product function such as alignment, crop guidance, map/route orientation, timeline reading, measurement, status, or motion continuity.
+4. Measurement, calibration, crop, map, route, and inspection marks are task-bound overlays or control affordances.
+5. They must not become the page background, hero backdrop, or default visual texture.
+6. When a conceptual anchor (see [REF:FE-005]) and a forbidden visual motif conflict, the forbidden motif wins; translate the anchor into layout, hierarchy, density, typography, state behavior, materials, and interaction instead of literal decorative texture.
 
-## Accessibility
+## FE-014: Production Content Policy
 
-- WCAG 2.2 AA is the hard floor.
-- APCA is advisory perceptual tuning 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.
+1. Production UI must read as ship-ready: no visible testing, demo, sample, placeholder, lorem, TODO, coming soon, or scaffold labels unless they are intentional product states.
+2. User-facing workflows need an operable UI path; terminal-only core flows are valid only for CLI, developer-tool, or runbook products.
 
-## CSS Production Hardening
+## FE-015: Motion Implementation Budget
 
-- 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.
+1. Omit rich motion or spatial UI only after naming the product-fit reason and the replacement interaction quality.
+2. 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.
+3. 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.
+4. Keep reduced-motion, keyboard, loading, performance, mobile, and non-3D fallbacks explicit.
 
-## Implementation Boundaries
+## FE-016: Library and Design-Intent Discipline
 
-- Follow the shipped project stack and current repo patterns.
-- Do not hardcode Zustand, React Query, smart/dumb component doctrine, or framework-specific architecture as universal design law.
-- Keep structure feature-oriented when it improves maintainability.
-- Keep component states recognizable across hover, focus, loading, success, empty, and error.
-- Do not let repeated surfaces share one visual treatment by habit; repetition needs a product reason.
+1. 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.
+2. 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.