@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

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

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

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

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

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

@@ -1,200 +1,84 @@
-# Git Workflow — Clean History, Atomic Commits
-
-> Your git log is a changelog. If it reads like gibberish, your team is lost.
-
-## Commit Message Format: Conventional Commits (Enforced)
-
-```
-<type>(<scope>): <description>
-
-[optional body — explain WHY, not WHAT]
-[optional footer — Breaking changes, issue references]
-```
-
-### Types (Strict Set)
-| Type | When | Example |
-|------|------|---------|
-| `feat` | New feature | `feat(auth): add JWT refresh token rotation` |
-| `fix` | Bug fix | `fix(payment): handle race condition in checkout` |
-| `refactor` | Code restructuring (no behavior change) | `refactor(user): extract validation to separate service` |
-| `docs` | Documentation only | `docs(api): add OpenAPI schema for /orders endpoint` |
-| `test` | Adding/fixing tests | `test(cart): add edge case for empty cart discount` |
-| `chore` | Build, CI, config, dependencies | `chore(deps): upgrade prisma to 5.x` |
-| `perf` | Performance improvement | `perf(search): add index on users.email column` |
-| `style` | Formatting, semicolons (no logic change) | `style: apply prettier formatting` |
-| `ci` | CI/CD changes | `ci: add Node 20 to test matrix` |
-
-### Rules
-1. **Type is mandatory.** No commits without a type prefix.
-2. **Scope is required for module or feature changes.** Use the module/feature name.
-3. **Description is imperative mood.** "add", not "added" or "adds".
-4. **Max 72 characters** for the subject line.
-5. **Body explains WHY,** not what. The diff shows what.
-
-### ❌ BANNED Commit Messages
-```
-fix bug
-updates
-WIP
-asdf
-misc changes
-working now
-final fix
-fix fix fix
-```
-
 ---
-
-## Branching Model
-
-### Main Branches
-| Branch | Purpose | Merge Strategy |
-|--------|---------|---------------|
-| `main` | Production-ready code | Merge commit or squash |
-| `develop` | Integration branch (if using GitFlow) | Merge commit |
-
-### Feature Branches
-```
-Pattern: <type>/<ticket-id>-<short-description>
-
-Examples:
-  feat/AUTH-123-jwt-refresh
-  fix/PAY-456-checkout-race-condition
-  refactor/USER-789-extract-validation
-  chore/INFRA-101-upgrade-node-20
-```
-
-### Rules
-1. Branch from `main` (or `develop` if using GitFlow)
-2. Keep branches short-lived (max 2-3 days)
-3. Rebase on `main` before creating PR — don't merge main into your branch
-4. Delete branch after merge
-
+id_prefix: GIT
+domain: git-workflow
+priority: medium
+scope: governance
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - git-workflow
+  - git
+  - commit
+  - branch
+  - pull-request
+  - gitignore
 ---
 
-## Pull Request Standards
-
-### PR Size
-| Size | Lines Changed | Verdict |
-|------|--------------|---------|
-| Small | 1-100 | ✅ Ideal — easy to review |
-| Medium | 100-300 | ⚠️ Acceptable — split if possible |
-| Large | 300-500 | 🔶 Needs justification |
-| Massive | 500+ | ❌ MUST be split into smaller PRs |
-
-**Rule:** If a PR touches more than 5 files across different modules, it's doing too much. Split it.
-
-### PR Description Template
-```markdown
-## What
-Brief description of what this PR does.
-
-## Why
-Why this change is needed. Link to issue/ticket.
-
-## How
-High-level approach. Mention any non-obvious design decisions.
-
-## Testing
-- [ ] Unit tests added/updated
-- [ ] Integration tests (if applicable)
-- [ ] Manual testing steps
-
-## Screenshots (if UI change)
-Before | After
-```
-
-### PR Review Rules
-1. Every PR needs at least 1 approval
-2. Author resolves all comments before merge
-3. CI must pass (lint, test, build)
-4. No `// TODO` without a linked issue
-5. No `console.log` debugging statements in production code
-
----
-
-## Commit Atomicity
-
-### Rule: Each Commit Must Be a Complete, Working Unit
-
-```
-❌ BANNED sequence:
-1. feat(user): add user model          ← compiles? maybe
-2. fix: fix import                     ← fixing previous commit
-3. feat(user): add user service        ← compiles? probably
-4. fix: fix typo                       ← fixing previous commit
-5. feat(user): add user controller     ← finally works together
-
-✅ REQUIRED:
-1. feat(user): add user registration module
-   → Model, Service, Controller, Tests — all in one complete, working commit
-   → Or split into logical chunks that each compile and pass tests independently
-```
-
-**Rule:** Every commit on `main` should compile, pass lint, and pass tests. Use interactive rebase (`git rebase -i`) to squash fix-up commits before merging.
-
----
-
-## .gitignore Standards
-
-### MUST Ignore
-```
-# Dependencies
-node_modules/
-vendor/
-venv/
-__pycache__/
-.gradle/
-target/
-
-# Environment
-.env
-.env.local
-.env.*.local
-
-# IDE
-.idea/
-.vscode/settings.json
-*.swp
-*.swo
-.DS_Store
-Thumbs.db
-
-# Build output
-dist/
-build/
-out/
-*.min.js
-*.min.css
-
-# Logs
-*.log
-npm-debug.log*
-
-# OS
-.DS_Store
-Thumbs.db
-```
-
-### MUST Commit
-```
-.env.example           # Template with placeholder values
-.editorconfig          # Consistent formatting across IDEs
-.prettierrc            # Formatter config
-.eslintrc.*            # Linter config
-tsconfig.json          # TypeScript config
-docker-compose.yml     # Dev environment
-Makefile / Taskfile    # Standard commands
-```
-
----
-
-## The Git Health Check
-
-Before pushing:
-- [ ] All commits follow Conventional Commits format
-- [ ] No fixup commits (squash them)
-- [ ] Branch is rebased on latest main
-- [ ] CI passes locally (lint, test, build)
-- [ ] No secrets in any commit (check with `git log -p | grep -i "password\|secret\|key"`)
-- [ ] No merge commits in feature branch (rebase instead)
+# Git Workflow - Clean History, Atomic Commits
+
+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.