@ryuenn3123/agentic-senior-core 3.0.37 → 3.0.39

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

@@ -1,168 +1,130 @@
 # Bootstrap Dynamic Design Contract
 
-When a user requests UI, UX, frontend layout, screen, Tailwind, animation, or redesign work, create or refine:
-- `docs/DESIGN.md` for human-readable design reasoning
-- `docs/design-intent.json` for machine-readable design intent, guardrails, and review signals
+Use this prompt for UI, UX, frontend layout, screen, Tailwind, animation, 3D, canvas, or redesign work.
 
-This contract is a decision scaffold, not a style preset. It must guide the LLM to choose well from the current repo, current user brief, current project docs, and live official documentation when a technology or library claim matters.
+Create or refine:
+- `docs/DESIGN.md` for human-readable design reasoning.
+- `docs/design-intent.json` for machine-readable design intent, guardrails, and review signals.
 
-## Core Rule
+This contract is a decision scaffold, not a style preset. We guide the agent; we do not pick the final style, stack, framework, palette, typography, layout paradigm, or animation library offline.
 
-We guide the agent; we do not pick the final style, stack, framework, palette, typography, layout paradigm, or animation library offline.
+## Authority
 
-The agent must:
-1. Read [AGENTS.md](../../AGENTS.md), this prompt, [frontend-architecture.md](../rules/frontend-architecture.md), current UI code, current project docs, and existing design docs before UI edits.
-2. If `docs/DESIGN.md` or `docs/design-intent.json` exists, refine them instead of replacing them blindly.
+- Treat `.agent-context/` and current project docs as technical authority.
+- Treat `README.md` as overview, install, and user-facing context only. Do not use it as coding, architecture, or design authority when `.agent-context/` gives a stricter rule.
+- Use current repo evidence, product copy, route names, component names, user goals, and existing constraints as the source of truth.
+- Treat prior-chat visuals, unrelated project memory, benchmark screenshots, and famous-product aesthetics as tainted context unless the user explicitly approves continuity.
+- Keep external references non-copying; extract constraints only.
+- Before choosing a new UI, animation, scroll, 3D, canvas, chart, icon, styling, or component library, research current official docs.
+
+## Required Order
+
+1. Read `AGENTS.md`, this prompt, `../rules/frontend-architecture.md`, current UI code, current project docs, and existing design docs.
+2. Refine existing `docs/DESIGN.md` and `docs/design-intent.json`; do not replace them blindly.
 3. If either design doc is missing, create it before UI implementation.
-4. Use current repo evidence, product copy, route names, component names, user goals, and existing constraints as the source of truth.
-5. Treat prior-chat visuals, unrelated project memory, benchmark screenshots, and famous-product aesthetics as tainted context unless the user explicitly asks for continuity.
-6. When choosing a new UI, animation, styling, or component library, research current official docs and choose the latest stable compatible option for this project. Do not rely on offline defaults.
-7. Keep external references non-copying: extract constraints and reasoning only, never clone the surface.
-8. Record a Motion/Palette Decision before UI implementation; product categories are heuristics, not style presets, so override them with task, content density, brand intent, device/performance, and accessibility evidence.
+4. Record `motionPaletteDecision` before UI code; product categories are heuristics, not style presets.
+5. Encode `repoEvidence.designEvidenceSummary` when onboarding or detector evidence exists.
+6. Keep both design docs synchronized after implementation.
 
 ## Creative Commitment Gate
 
-Before broad compliance review or UI implementation, commit to one concrete creative direction and record it in `docs/DESIGN.md` plus `docs/design-intent.json`. This commitment must include:
-- one conceptual anchor from a specific physical, editorial, architectural, cinematic, industrial, scientific, or interaction domain
-- one signature motion behavior that is more specific than "smooth transitions"
-- one typographic decision that creates meaningful role contrast instead of a uniform safe type system
+Before broad compliance review or UI implementation, record an agent-chosen visual direction in both design docs:
+- one concrete real-world anchor reference
+- one signature motion behavior more specific than "smooth"
+- one typographic decision with meaningful role contrast
+- one authored visual bet visible in the first viewport
 
-The anchor must name at least one specific real-world reference point such as a material, instrument, artifact class, architectural system, editorial genre, cinematic interface behavior, exhibition system, scientific apparatus, or industrial mechanism. If the anchor can only be described with generic quality words such as "modern", "clean", "premium", "expressive", "minimal", or "bold", reject it and choose again.
+Reject generic anchors. Do not accept "modern", "clean", "premium", "expressive", "minimal", or "bold" as the anchor. Name a material, instrument, artifact class, architectural system, editorial genre, cinematic behavior, exhibition system, scientific apparatus, or industrial mechanism.
 
-When the host supports separate agents, a lightweight creative pass may synthesize the commitment from the brief and repo evidence before a governance pass validates accessibility, tokens, maintainability, and implementation risk. When only one agent is available, perform the same separation sequentially: creative commitment first, governance validation second.
+## Dynamic Avant-Garde Anchor Engine
 
-## User Research Intake
+If no current-task research or visual reference exists, activate the Dynamic Avant-Garde Anchor Engine before coding.
 
-If the user mentions or attaches a research file, article, benchmark, library list, screenshot study, or design note, read it before choosing the visual direction or dependencies. Treat it as candidate evidence, not as a command to copy every recommendation.
+Rules:
+- Treat old design docs, prior UI, and scaffold seeds as evidence, not research.
+- Internally consider at least three high-variance anchors.
+- Discard the two safest or most predictable options.
+- Output only the chosen anchor, specific reference point, and rationale.
+- Forbid final anchors named dashboard, portal, cards, admin panel, SaaS shell, web app shell, or minimalist interface.
+- Derive typography, spacing, density, color behavior, morphology, motion, and responsive composition from the chosen anchor.
+- Use reduced-motion fallbacks instead of suppressing motion.
 
-The agent must summarize what it used from that research, discard what does not fit the project, and verify any library, framework, API, browser feature, or package claim against current official documentation before implementation.
+## Creative Ambition Floor
 
-User-supplied research may influence the candidate set for motion, scroll, UI primitives, canvas/3D, charts, icons, typography, and interaction patterns, but the final choice must still be project-fit, accessible, performant, and maintainable.
+Before UI code, record:
+- one product-derived palette move
+- one signature motion, spatial, or interaction behavior
+- one morphology or composition choice that avoids interchangeable card stacks when the product allows it
+- at least three at-a-glance product-specific signals for new screens or broad redesigns
 
-## Dynamic Avant-Garde Anchor Engine
+Do not ship AI-safe UI. Record exact drift signals in `reviewRubric`; at minimum reject decorative grid wallpaper, default line backgrounds, soft glow backgrounds, generic abstract marks, and first-output composition with only local copy swapped in when they have no product function.
 
-If the user requests UI work but provides no user-supplied research, design reference, screenshot study, or library note, do not start coding immediately. This is not permission to fall back to the scaffold, prior UI, or generic software metaphors. First synthesize one advanced conceptual anchor that will unify the interface.
+## AI Color and Template Residue Audit
 
-User-supplied research means current-task evidence from the user. The scaffold seed, this repo's offline examples, old design docs, and prior UI do not count as research. If live research is available, perform agent-led research into current official docs for any technology choices and current premium interaction/design patterns before selecting the anchor. If live research is unavailable, state that limitation in the design docs and synthesize from product context plus broad design knowledge without pretending the seed was research.
+AI color drift happens when a palette uses safe defaults before product meaning.
 
-Do not use basic software UI labels as the final anchor, including "dashboard", "portal", "cards", "admin panel", "SaaS shell", "web app shell", or "minimalist interface".
+Complete the AI color audit before coding:
+- Explain what product evidence or anchorReference makes the palette fit.
+- Name the color roles that carry task, status, data, or navigation meaning.
+- Name one color behavior that would not transfer cleanly to another product category.
+- Use visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity.
 
-The agent must internally consider at least three substantially different, high-variance candidate anchors, discard the two most obvious, safest, or easiest-to-predict options, then record only the surviving anchor, its concrete real-world reference point, and concise rationale. Do not expose hidden deliberation or the rejected candidate list.
+Cream, slate, monochrome, purple-blue gradients, cyber-neon terminals, pale editorial surfaces, soft glow atmospheres, and dark control rooms are autopilot risks, not banned palettes.
 
-The final anchor must come from broad non-template domains such as complex physical engineering, high-end industrial design, cinematic spatial interfaces, experimental editorial structure, advanced architecture, scientific instrumentation, advanced data visualization, exhibition/wayfinding systems, or premium interactive web experiences. These are search domains, not style presets.
+## Motion and 3D Courage Rule
 
-Write the chosen anchor into `docs/design-intent.json` as `conceptualAnchor`, including agentResearchMode, sourceDomain, specificReferencePoint, rationale, signatureMotion, typographicDecision, derivedTokenLogic, visualRiskBudget, motionRiskBudget, and cohesionChecks. Typography, spacing, density, color behavior, morphology, motion, and responsive composition must logically derive from that single anchor. If a later design choice does not follow from the anchor, revise the contract before coding.
+Motion, 3D, canvas, WebGL, scroll choreography, and modern animation libraries are first-class UI options when they improve understanding, exploration, feedback, hierarchy, memorability, or confidence.
 
-Motion is not a garnish. Default to a rich motion plan: fluid transitions, spatial reveals, scroll choreography, micro-interactions, and modern motion libraries are expected when they strengthen the anchor and product experience. Keep reduced-motion fallbacks instead of suppressing motion, and solve performance deliberately instead of using safety language as a reason to stay static.
+Use modern, expressive interaction when it improves hierarchy, feedback, confidence, or memorability.
 
-## Token Derivation Audit
+If rich motion or spatial UI is omitted, record the product, content-density, performance, accessibility, or device reason and the replacement interaction quality. "Not necessary" is not enough.
 
-Before implementation, `docs/design-intent.json` must include top-level `derivedTokenLogic` with `anchorReference`, `colorDerivationSource`, `spacingDerivationSource`, `typographyDerivationSource`, `motionDerivationSource`, and `validationRule`.
+If 3D or canvas is used, record product role, interaction model, fallback path, runtime/library choice, loading state, keyboard path, and reduced-motion behavior.
 
-After writing `docs/design-intent.json`, audit the token plan:
-- Why these colors instead of another palette? Answer in one sentence that references the anchorReference.
-- Why this spacing rhythm? Answer in one sentence that references the anchorReference.
-- Why this motion timing and easing? Answer in one sentence that references the anchorReference.
+## Token Derivation Audit
 
-If the answer is "looks good", "common practice", "modern default", "Tailwind default", or a generic framework habit, the token is wrong. Derive it again from the chosen anchor before writing UI code.
+Before implementation, `docs/design-intent.json` must include top-level `derivedTokenLogic`:
+- `anchorReference`
+- `colorDerivationSource`
+- `spacingDerivationSource`
+- `typographyDerivationSource`
+- `motionDerivationSource`
+- `validationRule`
+
+Every token must trace to `anchorReference`. If the rationale is "looks good", "common practice", "modern default", or "framework default", revise the token before code.
 
 ## Library Research Protocol
 
 If web search is available:
-- Research current official docs for each library, framework API, animation package, scroll tool, 3D/canvas helper, charting tool, icon package, or UI primitive claim.
-- Record source URL, fetched date, stable compatible version, purpose, risk, and fallback in `docs/design-intent.json`.
-- Set `libraryResearchStatus` to `verified` only when each external library decision has current official evidence.
+- Verify each new UI-related library against current official docs.
+- Record source URL, fetched date, stable compatible version, purpose, risk, and fallback in `libraryDecisions[]`.
+- Set `libraryResearchStatus` to `verified` only when every external library decision has evidence.
 
-If web search is unavailable or fails:
-- Do not hallucinate dependency APIs, package names, versions, or imports.
-- Write `LIBRARY_TO_VERIFY: [name] - requires live research before implementation` in the design notes.
-- Use only native CSS, browser APIs, or already-present project dependencies you can verify from local repo files.
-- Set `libraryResearchStatus` to `pending-verification` and give every `libraryDecisions[]` entry a `fallbackIfUnavailable`.
+If web search is unavailable:
+- Do not hallucinate package names, APIs, versions, or imports.
+- Use native CSS, browser APIs, or already-present dependencies.
+- Set `libraryResearchStatus` to `pending-verification`.
 
-Do not write imports from a new library until that library decision is verified or the user explicitly accepts a pending verification blocker.
+Treat unresearched dependency choices as review findings.
 
 ## Zero-Based Redesign Protocol
 
-If the user says "redesign from zero", "redesain dari 0", "ulang dari 0", "research ulang", or equivalent reset language, activate reset mode.
-
-In reset mode:
-- Existing UI and existing design docs are content, behavior, accessibility, and repo-evidence inputs only. They are not visual continuity sources.
-- Replace or materially rewrite `docs/DESIGN.md` and `docs/design-intent.json` before implementation so the new contract cannot inherit old palette, typography, layout, navigation shape, component morphology, motion signature, or image placement by accident.
-- Define a `visualResetStrategy` that names the old visual DNA being discarded and the new direction being selected from current brief, repo evidence, and live official documentation.
-- The implementation must change composition, hierarchy, palette/typography, motion/interaction, and responsive information architecture. A palette swap, dark-mode flip, or same hero with new colors is failure.
-- Keep product data, copy requirements, routes, accessibility needs, and required local assets intact unless the user explicitly says they may be removed.
-- If a modern UI, animation, scroll, 3D, canvas, chart, or icon library is useful, research current official docs and record the selected library, source URL, fetched date, reason, performance risk, and reduced-motion/accessibility fallback.
-
-## Design Quality Bar
-
-The UI must feel authored by a strong UI/UX designer, not assembled from default cards and safe framework chrome.
-The UI must not look like a first-pass AI template. "Readable" and "safe" are not enough when the brief calls for an authored product experience.
-
-## Creative Ambition Floor
-
-For new screens and broad redesigns, the agent must make one authored visual bet before coding. This can be a spatial structure, material logic, data treatment, motion language, typographic contrast, image system, or interaction model, but it must be visible in the first viewport and it must come from the chosen product anchor.
-
-The ambition floor is not a license to decorate. It is a check against timid AI-template output. The design may still be quiet, dense, utilitarian, or text-heavy when the product needs that, but it must have a clear authored decision that a generic scaffold would not produce.
+When the user says "redesign from zero", "redesain dari 0", "ulang dari 0", or "research ulang":
+- Treat existing UI as content, behavior, accessibility, and asset evidence only.
+- Rewrite or materially update both design docs before UI code.
+- Add `visualResetStrategy`.
+- Reset composition, hierarchy, palette/typography, motion or interaction, and responsive information architecture.
+- Do not ship a palette swap, dark-mode flip, or same hero with new colors.
 
-Before implementation, record:
-- one product-derived palette move that does not rely on cream, slate, purple-blue gradient, monochrome, or cyber-neon defaults
-- one signature motion, spatial, or interaction behavior that is more specific than "smooth"
-- one morphology or composition choice that breaks away from interchangeable card stacks when the product allows it
-
-If the agent chooses not to use rich motion, 3D, canvas, WebGL, scroll choreography, or an animation library, it must name the product, content-density, performance, accessibility, or device constraint that makes omission better. "Not necessary", "keep it simple", or "avoid complexity" is insufficient without that evidence.
-
-## AI Color and Template Residue Audit
-
-AI color drift happens when a screen reaches for safe defaults before it understands the product: cream editorial surfaces, dark slate dashboards, purple-blue gradients, monochrome minimalism, neon cyber terminals, soft glow atmospheres, or arbitrary bright accents with no semantic behavior.
-
-These palettes are not banned when the product truly earns them. They are banned as autopilot. If one appears, the design contract must explain why that palette belongs to the product, how each semantic role behaves, and what product-specific color behavior prevents the UI from reading like a first-pass AI template.
-
-The palette audit must answer:
-- What product evidence or anchorReference makes these colors more appropriate than safer defaults?
-- Which color roles carry task, status, data, or navigation meaning beyond surface decoration?
-- Which color choice would not transfer cleanly to a different product category?
-
-Accessibility is the floor, not the personality. Do not use contrast compliance as an excuse to flatten the palette into generic cream, slate, monochrome, or gradient safety.
-
-## Motion and 3D Courage Rule
-
-Motion, 3D, canvas, WebGL, scroll choreography, and modern animation libraries are first-class UI options when they improve product understanding, exploration, feedback, hierarchy, memorability, or confidence.
-
-The agent must not suppress motion or spatial UI because it is afraid of implementation complexity. It must choose the richest responsible interaction model the product can support, then define reduced-motion, keyboard, loading, performance, and non-3D fallbacks.
-
-When 3D/canvas is not used, document the non-use reason and the replacement interaction quality that will carry the experience. When 3D/canvas is used, document its product role, interaction model, fallback path, and library/runtime decision before coding.
-
-Do:
-- Synthesize a visual direction from the project context and explain why it fits.
-- Choose color, typography, spacing, motion, density, and component morphology dynamically from the product and audience.
-- Make at least three at-a-glance product-specific signals visible on new screens or broad redesigns: for example a data treatment, physical metaphor, motion behavior, iconography system, spatial structure, or state language that would not transfer cleanly to a different product.
-- Use visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity. The design may be quiet, but it must not hide inside safe cream, slate, monochrome, or gradient defaults.
-- Use modern, expressive interaction and motion as part of the core design language, especially when it improves hierarchy, feedback, delight, confidence, or memorability.
-- Use 3D or spatial/canvas experiences as primary UI only when they improve product understanding or exploration while preserving navigation, content clarity, user actions, performance, accessibility, and non-3D fallbacks.
-- Keep frontend code clean, componentized, accessible, and easy to maintain.
-- Use tokens and semantic aliases so future changes do not require rewriting components.
-- Make design decisions explicit before coding, then implement consistently.
-
-Do not:
-- Ship AI-safe UI: predictable card stacks, rounded template panels, generic abstract marks, decorative grid wallpaper, beige or slate safety palettes, soft glow backgrounds, or first-output composition with only local copy swapped in.
-- Default to generic SaaS heroes, balanced card grids, soft startup gradients, or dashboard chrome without product rationale.
-- Use background lines, grids, scanlines, noise, glows, blobs, logos, or geometric decoration unless each motif has a named product function such as alignment, measurement, navigation, crop guidance, timeline reading, status, or motion continuity.
-- Let desktop, tablet, and mobile be the same design merely scaled down.
-- Let heading, body, data, and metadata collapse into one safe typographic treatment without rationale.
-- Reuse colors, layout shapes, or motion signatures from unrelated memory.
-- Add decorative animation that hurts clarity, accessibility, or runtime performance.
-- Let 3D visuals hide navigation, replace readable content, block core actions, or require a powerful device before the product can be understood.
-- Choose a dependency because this repo scaffold mentioned it. The LLM must verify fit from current project context and official docs.
-
-## Responsive Rule
+## Responsive Recomposition Plan
 
 Responsive design means recomposition, not resizing.
 
-For every UI task, define how major surfaces change across mobile, tablet, and desktop:
-- What is reordered, merged, hidden, disclosed, or promoted?
-- What interaction changes for touch and narrow screens?
-- What content priority changes by viewport?
-- What is explicitly forbidden, such as scale-only shrink or preserving desktop order without reason?
+Define viewport mutation rules:
+- Mobile: prioritize the first decisive action and touch flow.
+- Tablet: regroup surfaces without becoming a shrunken desktop.
+- Desktop: expose more context without defaulting to admin chrome.
+- For each viewport, name what is reordered, merged, hidden, disclosed, promoted, and forbidden.
 
 ## Required `docs/DESIGN.md` Sections
 
@@ -181,35 +143,36 @@ For every UI task, define how major surfaces change across mobile, tablet, and d
 
 ## Required `docs/design-intent.json` Behavior
 
-The JSON must stay machine-readable and project-specific. It should record:
-- the confirmed project context and assumptions to validate
-- agent-chosen visual direction, not scaffold-chosen direction
-- an `aiSafeUiAudit` or equivalent review signal that states why the screen is not interchangeable with a generic AI-generated template
-- `motionPaletteDecision` with motion density source, required interaction states, palette autopilot risk, and whether 3D/canvas is useful or unnecessary
-- `conceptualAnchor` and how typography, spacing, morphology, motion, and responsive composition derive from it when no external research was provided
-- `derivedTokenLogic` with exact `anchorReference` traceability for color, spacing, typography, and motion tokens
-- `libraryResearchStatus` plus `libraryDecisions[]` with verified source metadata or explicit native/project-local fallbacks
-- agent-chosen semantic color roles, typography system, spacing rhythm, and motion approach
-- token layering with primitive, semantic, and component tokens
-- viewport mutation rules for mobile, tablet, and desktop
-- interaction-state expectations for key components
-- accessibility hard floor and advisory readability checks
-- review rubric for distinctiveness, contract fidelity, hierarchy, responsive recomposition, motion discipline, and accessibility
-- forbidden patterns that are concrete bad habits for this project
-- repo evidence when available, including `repoEvidence.designEvidenceSummary`
+The JSON is the source of truth for machine review. It must stay project-specific and include:
+- confirmed project context and assumptions
+- agent-chosen visual direction
+- `motionPaletteDecision`
+- `conceptualAnchor`
+- `derivedTokenLogic`
+- `aiSafeUiAudit`
+- `tokenSystem`, `colorTruth`, `crossViewportAdaptation`, `motionSystem`, and `componentMorphology`
+- `accessibilityPolicy`
+- `designExecutionPolicy`
+- `designExecutionHandoff`
+- `reviewRubric`
+- `contextHygiene`
+- `libraryResearchStatus` and `libraryDecisions[]`
+- `forbiddenPatterns`
+- `repoEvidence.designEvidenceSummary` when available
 
 ## Accessibility and Review
 
-WCAG 2.2 AA is the hard floor. APCA may be used only as advisory perceptual tuning and must never waive a WCAG failure.
+WCAG 2.2 AA is the hard floor. APCA may be used only as advisory perceptual tuning.
+
+Define a review rubric that names drift signals and separates taste from failure.
 
-The review must block or flag:
+Block or flag:
 - inaccessible contrast, focus, target size, keyboard, auth, or dynamic-status behavior
 - scale-only responsive behavior
-- unresearched dependency choices
-- AI-safe UI drift: interchangeable card grids, safe cream/slate/monochrome palettes, generic abstract logos, decorative grid wallpaper, or a screen that can be renamed to another product without visual changes
-- palette choices that use readability as a reason to stay in safe defaults instead of deriving a richer but accessible palette from the product
 - default component-kit styling without product rationale
-- missing or disconnected `conceptualAnchor` when no external design research was provided
+- nonfunctional background effects, including decorative grid wallpaper
+- grid or line backgrounds used as filler instead of product function
+- palette choices that use readability as an excuse for safe defaults
 - visual direction copied from unrelated memory or external references
 - genericity findings that cannot name the exact drift signal
 

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

@@ -1,116 +1,100 @@
 # Frontend Design and Interaction Boundaries
 
-UI work must load the smallest relevant surface, not the entire engineering handbook.
+Load this rule for UI-facing work. Keep the loaded surface small.
 
-## Auto Activation
-When the request is UI-facing, this rule activates automatically.
+## Activation
 
-UI scope triggers:
-- ui, ux, page, screen, component, layout, landing, dashboard, form, onboarding, animation, interaction
+Use this rule for:
+- 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.
-
-## Zero-Based Redesign Boundary
-
-- If the user asks for a redesign "from zero" or equivalent reset language, treat existing UI as behavioral/content evidence only, not as visual direction.
-- Do not preserve prior palette, typography, hero composition, navigation placement, component morphology, motion signature, or image framing unless the user explicitly requests continuity.
-- The new UI must materially recompose at least the primary surface, content hierarchy, interaction model, and responsive information architecture.
-- A dark-mode flip, same layout with different colors, or restyled version of the previous hero is not a zero-based redesign.
-- Record the visual reset in `docs/DESIGN.md` and `docs/design-intent.json` before coding.
-
-## 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 ship "AI-safe UI": predictable card stacks, rounded rectangles, generic abstract logos, decorative grids, beige or slate safety palettes, soft glow backgrounds, and first-output template composition are review findings when they are not directly required by the product.
-- 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 three visual, interaction, content, motion, or state behaviors must read as project-specific at a glance for new screens or broad redesigns. For a narrow component edit, at least one touched behavior must preserve or improve project specificity.
-- If the UI could be renamed to another product category without changing its composition, palette, iconography, and motion language, treat that as genericity drift and revise before implementation is considered complete.
-
-## Dynamic Avant-Garde Anchor Boundary
-
-- If the user gives no current-task visual research or reference, the scaffold, old UI, and existing design docs do not count as research.
-- Before UI code, choose one agent-synthesized conceptual anchor from high-variance non-software domains and record only the final anchor in `docs/design-intent.json`.
-- Before broad compliance review, record a creative commitment: one concrete real-world anchor reference, one signature motion behavior, and one typographic decision with meaningful role contrast.
-- Reject anchors that can only be described with generic quality words such as "modern", "clean", "premium", "expressive", "minimal", or "bold"; the anchor must name a specific material, instrument, artifact class, architectural system, editorial genre, cinematic behavior, exhibition system, scientific apparatus, or industrial mechanism.
-- Internally reject the safest dashboard, portal, card-grid, admin-shell, or minimalist-web-app mental model before writing CSS.
-- Typography, spacing, morphology, motion, and responsive recomposition must derive from the chosen anchor, not from framework defaults.
-- Token choices must trace to `docs/design-intent.json` `derivedTokenLogic.anchorReference`. A color, spacing, typography, or motion token that cannot be explained from the anchor is invalid.
-- Default to an expressive motion plan derived from the anchor. Use spatial transitions, micro-interactions, scroll choreography, and modern animation libraries when they improve the experience; include reduced-motion and performance safeguards without using them as an excuse for a static UI.
-
-## Library Research Boundary
-
-- New UI, animation, scroll, 3D, canvas, charting, icon, styling, or primitive libraries require current official-doc verification before imports are written.
-- If live research is unavailable, mark `libraryResearchStatus` as `pending-verification`, record the library as `LIBRARY_TO_VERIFY`, and use native CSS, browser APIs, or already-present project dependencies until verification is possible.
-- Each `libraryDecisions[]` entry must have either verification metadata or a concrete `fallbackIfUnavailable`.
-
-## Contextual Motion and Palette Intelligence
-
-- Product categories are heuristics, not style presets. Use them only as a starting signal, then choose motion density from user task, content density, brand intent, device/performance budget, and accessibility needs.
-- If the category is unclear, infer from the dominant task: reading, scanning, form completion, data comparison, product inspection, storytelling, learning, play, or spatial exploration.
-- For interactive UI, map the required states before coding: default, hover, focus-visible, active/pressed, disabled, loading, empty, error, success, and transition.
-- Prefer visually exploratory, product-derived palettes over safe template palettes. High readability is mandatory, but readability must not be used as an excuse for cream/beige/tan, dark slate, purple-blue gradients, monochrome palettes, or uniform card surfaces.
-- Do not default to dark slate, cream/beige/tan, purple-blue gradients, monochrome palettes, or uniform card surfaces unless current project evidence supports them. If one of those palettes is used, document why it fits, add enough role contrast that the UI does not read as a template, and include at least one product-specific color behavior that would not make sense in a generic SaaS screen.
-- Treat cyber-neon terminal palettes, pale editorial cream surfaces, anonymous dark control rooms, soft glow gradients, and monochrome minimalism as autopilot risks, not reusable defaults. They are valid only when the product anchor explains their task role.
-- Palette review must answer why these colors belong to this product, which semantic roles carry task/status/data meaning, and what color behavior would not transfer cleanly to another product category.
-- Background lines, grids, scanlines, noise, glows, blobs, abstract logos, and decorative geometry are invalid when used as wallpaper. They must serve a named product function such as alignment, crop guidance, map/route orientation, timeline reading, measurement, status, or motion continuity.
-- Use the existing motion stack first. Add animation, 3D, canvas, or scroll dependencies only when they materially improve delivery speed, interaction quality, maintainability, or product understanding.
-- Motion should be absent only for a named reason: repeated high-frequency workflow, long-form reading focus, data-density scanning, reduced-motion need, device budget, or performance constraint.
-- If rich motion, 3D, canvas, WebGL, scroll choreography, or animation libraries are omitted, the design contract must name the product-fit reason and the replacement interaction quality that will carry hierarchy, feedback, or memorability.
-
-## Spatial and 3D Experience Boundary
-
-- 3D, WebGL, canvas, and immersive spatial interfaces are allowed as the primary experience when they clarify the product, strengthen the chosen anchor, or make exploration meaningfully better than a flat UI.
-- 3D must not take over the jobs of navigation, content comprehension, or decisive user actions. Core routes, text, forms, and calls to action must remain discoverable, accessible, and usable without solving the scene.
-- Treat 3D as interaction architecture, not decoration. If it is only a modern-looking background or visual stunt, reduce it to a supporting accent or remove it.
-- Do not reject 3D/canvas by habit. Reject it only after naming the product, content-density, performance, accessibility, or device constraint that makes a non-3D interaction stronger.
-- Define performance and accessibility fallbacks before implementation: reduced motion, keyboard reachable controls, readable non-canvas content, mobile budgets, loading states, and a graceful non-3D path when rendering fails.
-- When 3D is central, document its product role, interaction model, fallback path, and library/runtime decision in `docs/DESIGN.md` and `docs/design-intent.json` before coding.
-
-## 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 should be expressive by default for modern UI work. Make it strengthen hierarchy, feedback, or memorability, then keep it reduced-motion-safe and performant.
+- frontend deliverables inside fullstack or backend work
+
+## Authority
+
+- 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 overview/install/user 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.
+- Keep design continuity opt-in. Repo evidence outranks memory residue.
+
+## Required Design Contract
+
+Before UI code, create or refine:
+- `docs/DESIGN.md`
+- `docs/design-intent.json`
+
+The contract must record:
+- `motionPaletteDecision`
+- `conceptualAnchor`
+- `derivedTokenLogic`
+- `aiSafeUiAudit`
+- `designExecutionPolicy`
+- `designExecutionHandoff`
+- `reviewRubric`
+- `contextHygiene`
+- `libraryResearchStatus` and `libraryDecisions[]`
+
+## Anti-Generic UI 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.
+
+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.
+
+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.
+
+Background lines, grids, scanlines, noise, glows, blobs, abstract logos, 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.
+
+## Dynamic Anchor Gate
+
+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.
+- 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.
+- Reject anchors described only by generic quality words such as modern, clean, premium, expressive, minimal, or bold.
+
+## Motion, Palette, and 3D
+
+- 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.
+- 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.
+- Keep reduced-motion, keyboard, loading, performance, mobile, and non-3D fallbacks explicit.
+
+## Zero-Based Redesign
+
+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.
+
+## Responsive Mutation
+
+Responsive quality is not scale-only.
+
+- 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.
+
+## Accessibility
+
+- 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.
 
 ## 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.
+- 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.

package/.agent-context/state/README.md

@@ -0,0 +1,26 @@
+# State Artifacts
+
+Use this directory as a typed governance state surface, not as a dump folder.
+
+Tracked seed/config artifacts:
+- `architecture-map.md`
+- `dependency-map.md`
+- `benchmark-comparison-schema.json`
+- `benchmark-reproducibility.json`
+- `benchmark-thresholds.json`
+- `benchmark-watchlist.json`
+- `benchmark-writer-judge-config.json`
+- `memory-adapter-contract.json`
+- `memory-schema-v1.json`
+- `stack-research-snapshot.json`
+
+Tracked operational artifact:
+- `onboarding-report.json` stays tracked in this repository because internal audits read it as the current repository onboarding state. In installed projects, `init` and `upgrade` regenerate this file.
+
+Local-only/generated artifacts:
+- `active-memory.json`
+- `v3-purge-audit.json`
+- `llm-judge-report.json`
+- benchmark, trend, weekly governance, and quality report outputs
+
+Do not treat generated reports as current project truth. Rerun the matching `npm run benchmark:*`, `npm run report:*`, or `npm run audit:*` command when fresh evidence is needed.