@ryuenn3123/agentic-senior-core 4.3.2 → 4.3.5

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

@@ -2,40 +2,15 @@
 id_prefix: ERR
 domain: error-handling
 priority: high
-scope: all-tasks
-applies_to:
-  - backend
-  - frontend
-  - fullstack
-keywords:
-  - error-handling
-  - err
-  - error
-  - handling
-  - boundary
-  - reject
+scope: backend
+applies_to: [backend, frontend, fullstack]
+keywords: [error-handling, errors, exception]
 ---
 
 # Error Handling Boundary
 
-Use the target language and framework's normal error model. Do not invent a custom exception architecture from this repo.
-
-## 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
-
-## ERR-002: Backend API error rules
-
-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.
+## ERR-001: Execution Rules
+1. Fail fast on invalid input.
+2. Do not leak stack traces to clients. Log them securely.
+3. Use standardized machine-readable error codes (RFC 9457).
+4. Distinguish client errors (4xx) from server errors (5xx).

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

@@ -3,40 +3,14 @@ id_prefix: EVT
 domain: event-driven
 priority: medium
 scope: backend
-applies_to:
-  - backend
-  - fullstack
-keywords:
-  - event-driven
-  - evt
-  - events
-  - consumers
-  - outbox
-  - consistency
+applies_to: [backend, fullstack]
+keywords: [event-driven, events, kafka, rabbitmq]
 ---
 
-# Event Boundary
+# Event Driven Boundary
 
-Do not add event-driven architecture because it sounds modern. Use it only when the product or repo shows a real async boundary.
-
-## EVT-001: Event Boundary and Hard Delivery Rules
-
-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.
-
-## EVT-002: Event Recovery and Catalogs
-
-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.
+## EVT-001: Execution Rules
+1. Events must be immutable.
+2. Consumers must be idempotent.
+3. Handle out-of-order events securely.
+4. Always implement Dead Letter Queues (DLQ) for poison messages.

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

@@ -4,169 +4,51 @@ domain: frontend-architecture
 priority: high
 scope: ui
 last_validated: 2026-05-17
-applies_to:
-  - frontend
-  - fullstack
-keywords:
-  - frontend-architecture
-  - fe
-  - ui
-  - design
-  - interaction
-  - boundaries
+applies_to: [frontend, fullstack]
+keywords: [frontend-architecture, fe, ui, engineering]
 ---
 
-# Frontend Design and Interaction Boundaries
+# Frontend Engineering Invariants (Tier 2)
 
-Load this rule for UI-facing work. Keep the loaded surface small.
-
-## 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
-
-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. Use the current date as the freshness anchor for design research. Trend and category-default claims should come from the newest relevant evidence, preferably material published or updated within the last 24 months. Older sources are acceptable only as labeled durable principles, not proof that a direction is currently modern.
-7. Treat user-provided concepts as first-class constraints. Adapt research to support, refine, or challenge the concept with evidence; do not override it with trend defaults unless a concrete product, accessibility, technical, or evidence conflict is recorded.
-8. Keep research vocabulary internal. Evidence, dossier, anchor, category-code, morphology, rename-test, and freshness labels may guide decisions, but must not appear in UI copy, public-facing docs, or final user-facing rationale unless the user explicitly asks for the research trace.
-9. 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.
-10. 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.
-11. Keep design continuity opt-in. Repo evidence outranks memory residue.
-
-## FE-003: Required Design Contract
-
-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[]`.
-
-## FE-004: Anti-Generic UI Gate
-
-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.
-
-## FE-005: Dynamic Anchor Gate
-
-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.
-
-## FE-006: Motion, Palette, and 3D
-
-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.
-
-## FE-007: Zero-Based Redesign
-
-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.
-
-## FE-008: Responsive Mutation
-
-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.
+Load this rule for UI-facing engineering work. This file contains strict engineering constraints.
 
 ## FE-009: Accessibility
-
-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]).
+1. WCAG 2.2 AA is the hard floor. APCA is advisory perceptual tuning only.
+2. Hard checks: focus visibility, target size, keyboard access, color-only meaning.
 
 ## FE-010: CSS Production Hardening
-
-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.
+1. Plan overflow, wrapping, truncation, empty, loading, and error behavior.
+2. Prefer logical composition primitives (container queries, subgrid).
 
 ## FE-011: Implementation Boundaries
-
 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.
+2. Do not hardcode Zustand, React Query, smart/dumb component doctrine.
 
 ## FE-012: Data State Surface
-
-1. Every data-displaying surface must explicitly handle, with distinct UI, the period before any data has arrived for the first time, the case where the result set is empty by query or by absence, the case where prior data is visible while new data fetches in the background, recoverable error, and limited-connectivity or cached-fallback when the product operates outside continuous network coverage.
-2. The surface must not collapse multiple data states into a single generic spinner, a single generic empty illustration, or a single generic error message; each state carries different operator and user information and must be distinguishable at a glance.
-3. Do not treat a stale-while-revalidate refresh as a loading state; show the prior data with a visible freshness indicator and update in place when the new result arrives.
-4. Status changes between these states must be announced to assistive technology through the platform's accessible-status mechanism, per WCAG 2.2 status-message guidance, so non-visual users learn that the surface moved from loading to populated, populated to empty, or populated to error.
-5. Reject "spinner everywhere" as the default UI for any non-trivial data surface. Reject empty states that look identical to error states. Reject error states that do not name a recovery path.
+1. Explicitly handle empty, loading, error, and offline states.
+2. Reject "spinner everywhere".
 
 ## FE-013: Background and Wallpaper Discipline
-
-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.
+1. Decorative geometry are invalid as wallpaper.
+2. Use grids/lines only for specific functional roles (alignment, map, crop).
 
 ## FE-014: Production Content Policy
-
-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.
+1. No visible testing, demo, sample, placeholder, lorem, or TODO labels in production UI.
 
 ## FE-015: Motion Implementation Budget
-
-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.
+1. Keep reduced-motion, keyboard, loading, performance, and mobile fallbacks explicit.
 
 ## FE-016: Library and Design-Intent Discipline
-
-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.
+1. Use component kits or headless primitives for behavior and accessibility when they fit.
 
 ## FE-017: Interactivity Priority
-
-1. Components that require client-side state, event handling, or interactive behavior must be the smallest unit that genuinely needs them. Wrapping, layout, narrative, and content-presentation components must remain server-rendered or static unless they themselves manage state or handle events.
-2. The interactive boundary must be drawn deliberately. Promoting a wrapper to client-side just to host a deeper child's interactivity is a defect.
-3. Use the platform's primitive for interactivity-priority hints (component-level interactivity boundaries, partial hydration, islands, or the framework equivalent) rather than a global default that hydrates everything.
-4. Operationally, measure responsiveness through Interaction to Next Paint (INP) or the platform's current Core Web Vitals threshold; a regression in INP that originates from over-eager interactivity is a defect, not a runtime cost to accept.
-5. Reject "make the whole page interactive so this one button works". Reject promoting a layout component to interactive without a recorded reason. Reject defaulting to a heavyweight client-side runtime when the surface is read-only.
+1. The interactive boundary must be drawn deliberately. Keep client-side state boundaries small.
+2. Measure responsiveness through Interaction to Next Paint (INP).
 
 ## FE-018: Internationalization as Layout
-
-1. Direction-sensitive spacing, alignment, and positioning must use direction-agnostic properties: CSS logical properties (`margin-inline-start`, `padding-block-end`, `inset-inline`, `border-inline-end`) or the framework or design-token equivalent. Physical-direction properties (`margin-left`, `padding-right`, `left`, `border-right`) are forbidden in shared layout code that may render in any locale.
-2. Icons must be classified at design time as direction-conveying (arrows, send/forward, undo/redo, slider handles, chevrons that imply navigation) or object-representing (a magnifying glass, a clock face, a brand mark). Direction-conveying icons must mirror with layout direction; object-representing icons must not. Decisions must be recorded in the icon system, not improvised per use.
-3. Plan a documented text-expansion budget for the project's target locales: short labels in some languages expand by 30 to 100 percent versus English, and the layout must absorb that growth without truncation, overflow, or breaking visual hierarchy. Record the assumed budget per surface and verify representative long-string fixtures during review.
-4. Bidirectional content (mixed left-to-right and right-to-left runs in a single string) must use the platform's bidi isolation primitive so a single embedded token cannot reorder surrounding content.
-5. Reject hardcoded physical-direction properties in shared codebases. Reject icon mirroring decisions left to per-component improvisation. Reject "we will fix it when we localize" as a substitute for a documented expansion budget.
+1. Direction-sensitive spacing, alignment, and positioning must use CSS logical properties (e.g., `margin-inline-start`).
+2. Plan a documented text-expansion budget for target locales.
 
 ## FE-019: Theme as Context
-
-1. A theme switch is a change in lighting and surface model, not a color inversion. The same brand color does not produce the same perceptual result against a high-luminance surface as against a low-luminance surface; tokens must be re-derived per theme, not algebraically inverted.
-2. Elevation and depth must be expressible without depending on drop-shadows alone. Drop-shadows lose contrast at low surface luminance; depth tokens must combine surface-color shifts, border treatments, or platform-equivalent material cues so the elevation hierarchy remains legible across themes.
-3. Brand colors carried across themes must be individually verified against the active theme's contrast floor. Two colors with identical chroma can pass contrast on one theme and fail on another; per-theme verification is mandatory and cannot be substituted with a single light-mode test.
-4. Theme tokens must include explicit mappings for status (success, warning, error, info), focus-visible, and disabled states per theme. A token that exists only on one theme is incomplete.
-5. Reject color inversion as a substitute for a re-derived theme. Reject reliance on drop-shadows as the sole elevation cue. Reject deferring per-theme contrast verification to runtime.
-6. Authority for the perceptually-uniform color reasoning above is illustrative across modern color-science work; the OKLCH color space is one example of a perceptually-uniform space and may be used to express tokens, but it is not required. The universal fallback for delivery is sRGB; on platforms or surfaces where wide-gamut delivery is supported and verified, wider color spaces may be used. Verify the platform's current color-management capabilities at audit time.
-<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->
+1. A theme switch is a change in lighting and surface model, not a color inversion. Re-derive tokens per theme.
+2. Brand colors carried across themes must be individually verified against the active theme's contrast floor.

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

@@ -2,83 +2,14 @@
 id_prefix: GIT
 domain: git-workflow
 priority: medium
-scope: governance
-applies_to:
-  - backend
-  - frontend
-  - fullstack
-keywords:
-  - git-workflow
-  - git
-  - commit
-  - branch
-  - pull-request
-  - gitignore
+scope: all-tasks
+applies_to: [backend, frontend, fullstack]
+keywords: [git-workflow, git, commit, pr]
 ---
 
-# Git Workflow - Clean History, Atomic Commits
+# Git Workflow Boundary
 
-Your git log is a changelog. If it reads like gibberish, your team is lost.
-
-## GIT-001: Commit Message Format (Conventional Commits Enforced)
-
-1. Use Conventional Commits for every commit: `<type>(<scope>): <description>`.
-2. Use the optional body to explain WHY, not WHAT.
-3. Use the optional footer for breaking changes and issue references.
-4. Use only the strict types set: `feat` for new feature, `fix` for bug fix, `refactor` for code restructuring with no behavior change, `docs` for documentation only, `test` for adding or fixing tests, `chore` for build, CI, config, or dependencies, `perf` for performance improvement, `style` for formatting and semicolons with no logic change, and `ci` for CI/CD changes.
-5. Type is mandatory. No commits without a type prefix.
-6. Scope is required for module or feature changes. Use the module or feature name.
-7. Description must use imperative mood: "add", not "added" or "adds".
-8. Keep the subject line at max 72 characters.
-9. Body explains WHY; the diff shows what.
-10. Reject banned commit messages: `fix bug`, `updates`, `WIP`, `asdf`, `misc changes`, `working now`, `final fix`, and `fix fix fix`.
-
-## GIT-002: Branching Model and Merge Strategy
-
-1. Keep `main` production-ready; its purpose is production-ready code, and its merge strategy is merge commit or squash according to project policy.
-2. Use `develop` as an integration branch only when the project uses GitFlow; its purpose is integration.
-3. Name feature branches with the pattern `<type>/<ticket-id>-<short-description>`.
-4. Example branch names include `feat/AUTH-123-jwt-refresh`, `fix/PAY-456-checkout-race-condition`, `refactor/USER-789-extract-validation`, and `chore/INFRA-101-upgrade-node-20`.
-5. Branch from `main`, or from `develop` when using GitFlow.
-6. Keep branches short-lived, max 2-3 days.
-7. Rebase on `main` before creating a PR; do not merge main into your branch.
-8. Delete the branch after merge.
-
-## GIT-003: Pull Request Standards
-
-1. Keep PR size reviewable: small is 1-100 lines changed and ideal because it is easy to review; medium is 100-300 and acceptable, split if possible; large is 300-500 and needs justification; massive is 500+ and must be split into smaller PRs. Treat these thresholds as the PR size verdict.
-2. Split a PR when it touches more than 5 files across different modules; it is doing too much.
-3. PR descriptions must follow the PR Description Template: What, Why, How, Testing, and Screenshots when the change affects UI.
-4. What gives a brief description of what the PR does.
-5. Why explains why the change is needed and links to the issue or ticket.
-6. How gives the high-level approach and mentions non-obvious design decisions.
-7. Testing lists unit tests, integration tests when applicable, and manual testing steps.
-8. Every PR needs at least 1 approval, author resolves all comments before merge, CI must pass lint, test, and build, no `// TODO` appears without a linked issue, and production code contains no `console.log` debugging statements.
-
-## GIT-004: Commit Atomicity
-
-1. Each commit must be a complete, working unit.
-2. Reject banned sequences where a feature commit is followed by fix imports, fix typos, or other fix-up commits needed to make the previous commit work.
-3. Prefer one complete working commit for a cohesive module, such as model, service, controller, and tests for user registration.
-4. Split into logical chunks only when each chunk compiles and passes tests independently.
-5. Every commit on `main` should compile, pass lint, and pass tests.
-6. Use interactive rebase (`git rebase -i`) to squash fix-up commits before merging.
-
-## GIT-005: .gitignore Standards
-
-1. Ignore dependency and cache directories: `node_modules/`, `vendor/`, `venv/`, `__pycache__/`, `.gradle/`, and `target/`.
-2. Ignore environment files: `.env`, `.env.local`, and `.env.*.local`.
-3. Ignore IDE and OS artifacts: `.idea/`, `.vscode/settings.json`, `*.swp`, `*.swo`, `.DS_Store`, and `Thumbs.db`.
-4. Ignore build output: `dist/`, `build/`, `out/`, `*.min.js`, and `*.min.css`.
-5. Ignore logs: `*.log` and `npm-debug.log*`.
-6. Commit configuration templates and formatter or linter config: `.env.example`, `.editorconfig`, `.prettierrc`, `.eslintrc.*`, and `tsconfig.json`.
-7. Commit standard development commands and environments when they are part of the project contract: `docker-compose.yml`, `Makefile`, or `Taskfile`.
-
-## GIT-006: Git Health Check
-
-1. Before pushing, verify all commits follow Conventional Commits format.
-2. Before pushing, verify there are no fixup commits; squash them.
-3. Before pushing, verify the branch is rebased on latest main.
-4. Before pushing, verify CI passes locally: lint, test, and build.
-5. Before pushing, verify there are no secrets in any commit; check with `git log -p | grep -i "password\|secret\|key"`.
-6. Before pushing, verify there are no merge commits in the feature branch; rebase instead.
+## GIT-001: Execution Rules
+1. Enforce .gitignore standards. NEVER commit .env or secrets.
+2. Write semantic commit messages (feat:, fix:, chore:).
+3. Keep commits atomic and focused.

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

@@ -3,42 +3,14 @@ id_prefix: SVC
 domain: microservices
 priority: medium
 scope: backend
-applies_to:
-  - backend
-  - fullstack
-keywords:
-  - microservices
-  - svc
-  - monolith
-  - contracts
+applies_to: [backend, fullstack]
+keywords: [microservices, monolith]
 ---
 
-# Service Boundary Rule
+# Microservices Boundary
 
-The agent must infer the right topology from the user brief, repo evidence, team/runtime constraints, and live official docs when technology choices matter.
-
-## SVC-001: Monolith Boundary
-
-1. Do not ask for or force "monolith vs microservices" as an init default.
-2. Do not start with microservices by fashion, fear, or habit.
-3. Use a single deployable system when one team or one delivery stream owns most changes.
-4. Use a single deployable system when feature boundaries can stay clear inside one repo/process.
-5. Use a single deployable system when synchronous data consistency is more valuable than distributed autonomy.
-6. Use a single deployable system when observability, CI/CD, and operational maturity are still forming.
-7. Keep feature/domain boundaries explicit.
-8. Do not let one giant shared module become the real architecture.
-9. Keep contracts clear between modules.
-10. Refactor toward cleaner seams before extracting services.
-
-## SVC-002: Service Split Boundary and Hard Rules
-
-1. Split a service only when current evidence justifies the operational cost.
-2. Valid split signals include independent deploy cadence that is already painful; materially different scale, latency, security, or compliance needs in one domain; stable ownership boundaries plus repeated coupling causing delivery risk; failure isolation as a real product or business requirement; and service contract plus data ownership documentation before extraction.
-3. Hard rules: each service owns its data boundary.
-4. Public service contracts must be documented before implementation or extraction.
-5. Cross-service calls need timeout, retry, idempotency, observability, and recovery behavior.
-6. Independent services must not use shared tables as their integration contract; communicate through documented APIs, events, or async workflows owned by the source domain.
-7. Avoid synchronous call chains that turn services into a distributed monolith.
-8. Critical cross-service mutations should prefer local transactions plus outbox, saga, choreography, orchestration, or compensating actions over two-phase commit by default.
-9. Prefer incremental extraction over rewrites.
-10. If the evidence is unclear, document the uncertainty and keep the topology agent-recommended instead of pretending an offline default is correct.
+## SVC-001: Execution Rules
+1. Default to modular monoliths unless scale explicitly dictates microservices.
+2. Independent services must own their data. NO shared databases.
+3. Cross-service calls must have timeouts and retries.
+4. Prefer async choreographies over distributed two-phase commits.

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

@@ -1,84 +1,16 @@
 ---
 id_prefix: MIG
 domain: migrations
-priority: critical
+priority: high
 scope: data
-last_validated: 2026-05-17
-applies_to:
-  - backend
-  - fullstack
-keywords:
-  - migrations
-  - schema
-  - ddl
-  - expand-contract
-  - backfill
-  - rollback
+applies_to: [backend, fullstack]
+keywords: [migrations, schema, database]
 ---
 
 # Migrations Boundary
 
-A schema or data-shape change that touches live traffic is a deployment with two moving parts: the schema and the code that depends on it. Migrations safety is the property that the user-facing operation continues to succeed during, and after, the change, regardless of which side ships first or which side rolls back. Vendor-specific online-migration tools that may appear in commentary are illustrative; the authority is the safety invariants below.
-
-## MIG-001: Hard rules (Mandatory)
-
-1. Every schema change that touches live data must be decomposed into expansion steps (additive, non-breaking, independently deployable) and contraction steps (removal of old structures), with at least one production deployment between phases. Single-step schema changes that simultaneously add and remove are forbidden on hot data.
-2. The deploy ordering invariant must hold across the entire migration: code that requires the new schema must not deploy before the migration that introduces it, and code that requires the old schema must not deploy after the migration that removes it. The ordering must be documented in the migration ticket and verified by the deploy procedure.
-3. A migration must be reversible, or it must carry a documented forward-only recovery plan. "We will figure it out" is not a recovery plan.
-4. Reject migrations that lack a rollback or recovery plan. Reject deploy procedures that allow a code revert to land while the schema is still in the new shape, or vice versa, without an explicit compensating step.
-
-## MIG-002: Lock posture (Mandatory)
-
-1. Any DDL operation expected to hold an exclusive or share lock for longer than the service's acceptable request-latency threshold must use the platform's online or non-blocking migration mechanism. The threshold is the service's own latency budget, not a fixed number of rows or a fixed wall-clock duration.
-2. Where the platform supports a two-phase mechanism for constraints (for example, validate-without-lock followed by an asynchronous validate, or platform-equivalent concurrent index creation), use it instead of a single locking statement. The implementation must record which phase is run in which deploy.
-3. Long-running statements must run with an explicit statement timeout or lock-wait timeout, so a stuck DDL cannot hold a global lock indefinitely.
-4. Reject DDL inside long-running transactions that also contain unrelated work. Reject foreign-key or check-constraint additions on hot tables in a single locking statement when the platform offers a non-blocking variant.
-
-## MIG-003: Backfills (Mandatory)
-
-1. Backfills are separate from DDL. The DDL adds the column, table, or index in its safe shape (nullable, no-default, or non-unique, as appropriate); the backfill populates or repairs data in idempotent, resumable batches.
-2. A backfill job must be idempotent: rerunning the job, including from an arbitrary mid-progress checkpoint, must converge to the same final state without double-writing or double-charging.
-3. A backfill job must be resumable. The job must record progress on a durable cursor so a process restart, deploy, or worker rotation does not require restarting from the beginning.
-4. A backfill job must be observable. It must emit progress, throughput, and error-rate telemetry; an operator must be able to answer "how far has the backfill progressed?" without reading the data store directly.
-5. A backfill job must be throttleable. It must respect the platform's load on the source data store, and an operator must be able to slow or pause it during incidents without losing progress.
-6. Reject "backfill in the migration script". Reject backfill jobs that do not record progress, that cannot be paused, or that have no completion criterion.
-
-## MIG-004: Risk documentation (Mandatory)
-
-Every migration ticket or change record must capture, at change time, the following:
-
-1. Estimated runtime on production-equivalent data volume.
-2. Lock posture: which locks the operation acquires, on which objects, for how long, and which queries it will block.
-3. Data volume estimate: rows or bytes touched.
-4. Rollback plan or, if forward-only, the recovery plan with explicit data-loss exposure.
-5. Deploy-ordering note: which application version range is safe with the old schema, which with the new, and which with both. Both-compatible windows are required for any change that touches a request path.
-6. Backfill plan, if any: what data is rewritten, in what batch shape, with what idempotency key.
-7. Verification step: the post-migration check the operator runs to confirm the schema, the data, and the application all match the intended end state.
-
-A change that ships without these fields is not a migration; it is a defect waiting to happen.
-
-## MIG-005: Boundary safety (Mandatory)
-
-1. Cross-service migrations must coordinate the schema change with the downstream consumers. A producer that drops a field before downstream consumers stop reading it is a breaking change disguised as a migration.
-2. Event payload schemas, message contracts, and shared cache shapes are subject to the same expand-contract discipline as relational schemas. Producers add the new shape first, consumers learn to read both, then producers retire the old shape.
-3. Reject "we control all consumers" as a substitute for the expand-contract discipline; consumers include retried events from before the deploy, mobile clients with stale code, and parallel-running canaries.
-
-## MIG-006: Reject these bad habits
-
-1. Reject one-shot DDL that adds and removes structures in the same deploy on hot data.
-2. Reject migrations that take an exclusive lock on a hot table without a non-blocking alternative tested first.
-3. Reject backfills baked into the migration transaction so the transaction cannot complete in time.
-4. Reject "feature-flag the schema" patterns where two code paths read or write incompatible shapes against the same column without an explicit migration plan.
-5. Reject migration tickets that omit the risk-documentation fields above.
-6. Reject claims of reversibility that are not actually exercised on a non-production environment before production deploy.
-
-## MIG-007: Citations and freshness
-
-Authority sources for the rules in this file:
-
-- The expand-contract or parallel-change pattern in mainstream continuous-delivery and database-refactoring literature: authority for the multi-phase deploy discipline.
-- Database engine documentation for the platform in use: authority for which DDL operations are non-blocking, which require a rewrite, which acquire what locks, and which support a two-phase validate. Verify the platform's current major-version documentation at audit time, because lock posture changes between major versions of the same engine.
-- IETF RFC 7807 and successor problem-detail specifications: authority for how a write that hits a deploy-ordering window should communicate its rejection to the caller.
-
-Vendor-specific online-migration tools (in any database ecosystem) are illustrative implementations of the lock-posture and backfill rules above; they are not authority. Use the platform-appropriate mechanism that exists in the deployed engine version.
-<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->
+## MIG-001: Execution Rules
+1. Schema changes MUST have a versioned migration.
+2. Migrations must be reversible (down-migrations) or have a recovery plan.
+3. Never modify past migrations once merged. Create a new one.
+4. Use concurrent index builds in production.

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

@@ -3,67 +3,14 @@ id_prefix: OBS
 domain: observability
 priority: high
 scope: backend
-last_validated: 2026-05-17
-applies_to:
-  - backend
-  - fullstack
-keywords:
-  - observability
-  - telemetry
-  - logs
-  - metrics
-  - traces
-  - slo
-  - alerts
+applies_to: [backend, fullstack]
+keywords: [observability, telemetry, logs, metrics]
 ---
 
 # Observability Boundary
 
-Observability is the property of a system that lets an operator answer, after the fact, which user, which code path, and which dependency caused a given outcome, using signals captured at runtime. Treat metrics, logs, and traces as derived views over structured per-request events; the underlying obligation is that the captured events are enough to reconstruct what happened, regardless of which storage shape a vendor calls a "pillar".
-
-## OBS-001: Hard rules (Mandatory)
-
-1. Every request, job, and message-handler invocation must emit a structured event that carries: a stable request or correlation identifier, the operation name, the upstream caller identity, the downstream dependencies it touched, the outcome status, and the duration. The event payload must be machine-parseable, not a free-text log line.
-2. Trace context must propagate across every in-process and cross-process boundary the system controls. The system must not drop or rewrite an inbound trace identifier; it must extend it.
-3. Logs, metrics, and traces must share the same correlation identifier so an operator can pivot between them without manual joining.
-4. Configuration of telemetry destinations, sampling rates, and log levels must come from runtime configuration; the system must not require a code change to redirect signals or to raise verbosity during an incident.
-5. The system must redact or omit secrets, tokens, full request and response bodies, and personal data from logs, metric labels, span attributes, and error reports. Identifiers, counts, sizes, and shapes are acceptable.
-6. The system must expose a documented health surface that distinguishes liveness, readiness, and startup where the runtime supports it. A `200 OK` that does not check critical dependencies is not a readiness signal.
-
-## OBS-002: Reject these bad habits
-
-1. Reject metric label cardinality that is unbounded by design. User identifiers, request identifiers, full URLs, raw query strings, and session identifiers must not be metric labels; they belong in event attributes that the storage tier can index without exploding cardinality.
-2. Reject vendor-proprietary instrumentation when an open standard provides equivalent coverage. Where the platform supports it, prefer instrumentation that exports through W3C Trace Context and OpenTelemetry semantic conventions so the backend storage choice can change without re-instrumenting the application.
-3. Reject substituting one signal for another. Do not parse free-text logs to derive metrics that should have been recorded as metrics. Do not search free-text logs to reconstruct call graphs that should have been recorded as traces. Each signal type carries different sampling, retention, and indexing trade-offs; collapsing them hides those trade-offs.
-4. Reject logging of full request bodies, headers containing authorization material, raw uploads, decrypted secrets, plaintext tokens, and direct personal identifiers. A log line that would leak a credential if forwarded to a third-party storage provider is a defect.
-5. Reject paging humans for symptoms that have no documented user impact. Do not page on raw resource utilization, on a single failed request, or on a single retry; page on a sustained breach of a documented service-level objective whose error budget has been spent.
-6. Reject "happy-path-only" telemetry. Error paths, retries, fallbacks, throttles, circuit transitions, and degraded-mode fallbacks must emit events of equal or higher fidelity than the success path; a system that is loud only when healthy is observable only when it is fine.
-7. Reject silent drops. The telemetry pipeline itself must report when it sheds events, drops spans, or rate-limits log output, so an operator can distinguish "no events" from "events lost".
-
-## OBS-003: SLOs and alerts (Mandatory)
-
-1. Every alert that pages a human must be backed by a documented service-level objective expressed in user-facing terms (availability of a journey, latency of a critical interaction, freshness of a derived dataset). Alerts without an SLO and an explicit error-budget intent are noise.
-2. SLO definitions must record: the user journey or contract being measured, the success criterion (status, latency threshold, freshness threshold), the measurement window, the target attainment, and the agreed action when the error budget burns at an elevated rate.
-3. Multi-window, multi-burn-rate alerting (or platform equivalent) is preferred so a fast burn pages quickly without amplifying flapping on slow burns. Single-threshold alerting on a raw counter is acceptable only when no error budget can be defined for the signal.
-4. Alert routing must distinguish actionable alerts (paged human required to recover the user journey) from informational alerts (record-only, dashboard-only). Pager rotations must not receive informational alerts.
-5. Telemetry retention windows must cover at least one full SLO measurement window plus the longest documented incident-investigation window the team commits to.
-6. Reject alerts whose runbook is "investigate the dashboard". Every actionable alert needs a documented next step that a non-author on-call can execute.
-
-## OBS-004: Audit and forensics (Mandatory)
-
-1. Security-relevant events (authentication outcomes, authorization decisions, privilege changes, data exports, configuration changes, key rotations) must be emitted on a separate, append-only event stream with stricter retention and access controls than operational telemetry.
-2. Audit events must record: who acted, what was acted upon, when, from which network identity, and the outcome. Source identity must come from the authenticated principal, not from a self-reported value in the request body.
-3. Audit-event storage must remain readable when the application's primary database is unavailable, or the audit event must be considered untrustworthy.
-4. Reject mixing audit events into the same low-retention, broadly readable channel as operational logs.
-
-## OBS-005: Citations and freshness
-
-Authority sources for the rules in this file:
-
-- W3C Trace Context (W3C Recommendation): the canonical contract for propagating `traceparent` and `tracestate` across boundaries. Verify the current Recommendation when authoring instrumentation that crosses an organizational boundary.
-- OpenTelemetry semantic conventions: the open-standard set of attribute names for traces, metrics, and logs across HTTP, RPC, messaging, and database operations. Use the version current at audit time; older fixed snapshots drift.
-- RFC 5424 (The Syslog Protocol): authority for severity ordering when mapping log levels onto a transport that requires it.
-- OWASP ASVS: requirements for security-relevant audit logging, including the events listed above as audit-stream candidates.
-
-These citations are illustrative anchors, not vendor endorsements. Vendor names that may appear in commentary (for example, the names of trace backends, log aggregators, or APM products) are not authority for this rule.
-<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->
+## OBS-001: Execution Rules
+1. Emit telemetry for failures, degraded states, and security events.
+2. Inject correlation IDs on inbound requests and propagate them downstream.
+3. Do not log PII, secrets, or credentials.
+4. Measure latency, traffic, errors, and saturation.