Imported from AlvaGonz/Proyecto-Estimacion-Soft (.agents/rules/AGENTS.md). Install upstream with npx skills add AlvaGonz/Proyecto-Estimacion-Soft --skill rules. Copyright stays with the author.

# AGENTS.md — Proyecto Estimación Software
**Updated:** 2026-03-05 | **Repo:** AlvaGonz/Proyecto-Estimacion-Soft
**Team:** Adrian Alvarez González, Ray Rubén Ventura López | **UCE — Ingeniería de Software**

---

## MISSION
Web platform for software estimation via **Wideband Delphi method**: iterative, anonymous, consensus-based estimation with full traceability.

## ARSENAL (Installed Skills)
- **Architecture**: `architecture-blueprint-generator`, `folder-structure-blueprint-generator`, `typescript-mcp-server-generator`.
- **Planning**: `create-specification`, `create-implementation-plan`, `breakdown-epic-arch`, `refactor-plan`.
- **Quality**: `javascript-typescript-jest`, `review-and-refactor`, `refactor-method-complexity-reduce`, `playwright-*`.
- **DevOps**: `multi-stage-dockerfile`, `devops-rollout-plan`, `gh-cli`.
- **Database**: `cosmosdb-datamodeling` (MongoDB), `sql-code-review`, `sql-optimization`.

---

## STACK

| Layer | Tech | Status |
|-------|------|--------|
| Frontend | React 18 + TypeScript 5.4 + Vite + Tailwind + Zod + jsPDF + xlsx | ✅ Phase 1 Done |
| Backend | Node.js 20 + Express 4.19 + TypeScript + Mongoose 8.2 | 🟡 Phase 2A Scaffolded |
| Database | MongoDB 8.x | 🔵 Planned |
| DevOps | Docker + GitHub Actions + Nginx | 🔵 Phase 2D |

**Auth:** JWT access (15m) + refresh (7d) in `httpOnly` cookies. bcrypt 12 rounds.

---

## ARCHITECTURE

[React SPA :5173] ──REST/HTTPS──> [Express API :4000] ──Mongoose──> [MongoDB :27017]

**Collections:** users, projects, tasks, rounds, estimations, comments, auditLogs

---

## PROJECT STRUCTURE

/ ← Frontend root ├── components/ ← Login, AdminPanel, ProjectForm, ProjectList, │ │ ProjectDetail, TeamPanel, EstimationRounds (22KB), │ │ DiscussionSpace, Documentation, NotificationCenter, │ │ ReportGenerator, ProjectAuditLog │ └── ui/ ← LoadingSpinner, EmptyState, ErrorBoundary, │ PermissionGate, OnboardingTour ├── utils/schemas.ts ← Zod client schemas ├── utils/rbac.ts ← Client RBAC helpers ├── types.ts ← Frontend types ├── App.tsx / index.tsx / vite.config.ts


---

## RBAC

| Role | Permissions |
|------|-------------|
| `admin` | All permissions |
| `facilitador` | `create:project` `edit:project` `manage:rounds` `generate:report` `moderate:discussion` |
| `experto` | `submit:estimation` only |

**Middleware order:** `authenticate → requireRole([...]) → validate(schema) → controller`

---

## REQUIREMENTS MAP

| Phase | RFs | RNFs | Status |
|-------|-----|------|--------|
| 1 – Frontend UI | RF001-003, RF006-019, RF023-024, RF028 | RNF006 | ✅ Done |
| 2A – Auth+DB | RF001-005 | RNF001-004, RNF007 | 🟡 Scaffolded |
| 2B – Domain | RF006-022 | RNF005, RNF008 | 🔵 Next |
| 2C – Services | RF009, RF023-030 | — | 🔵 Planned |
| 2D – DevOps | — | RNF001, RNF005 | 🔵 Planned |

---

## WIDEBAND DELPHI RULES ⚠️ NEVER MODIFY

**Round lifecycle:** `open → [anonymous estimates] → closed → [stats] → {converged | new_round}`

- **Open round:** Experts submit independently. NO visibility of others' estimates (enforced at server level, not just client).
- **Closed round:** Immutable (DB-level). Stats calculated. Anonymized results visible.

**Stats required (RF015):** mean, median, std dev, variance, CV, range, IQR
**Outlier detection (RF016):** IQR rule → `value > Q3 + 1.5×IQR` OR `value < Q1 − 1.5×IQR`
**Convergence (RF020):** CV < threshold AND outlier% < maxAllowed (both configurable per project)

**Services API:**
```typescript
statisticsService.calculateMetrics(estimates: number[]) → StatMetrics
convergenceService.evaluateConsensus(metrics, config) → { converged: boolean, recommendation: string }

API CONVENTIONS

Base: http://localhost:4000/api (dev)

Response format (always):

{ success: boolean; data?: T; message?: string; errors?: Record<string, string[]> }

REST routes:

GET/POST   /api/projects
GET/PATCH  /api/projects/:id
POST       /api/projects/:id/archive
GET/POST   /api/projects/:id/rounds
POST       /api/rounds/:id/close
GET/POST   /api/rounds/:id/estimations

CODE STANDARDS

TypeScript: strict=true, no any, named exports (except React components), I prefix only for Mongoose models (IUser, IProject)

Naming: files=camelCase.ts | components=PascalCase.tsx | constants=SCREAMING_SNAKE_CASE

React component order: imports → types → component → hooks → handlers → render

Express route order: asyncHandler(async (req, res) => { validate → authorize → business logic → respond })

FORBIDDEN ❌ (Hard Stops)

any type in TypeScript
Secrets committed to Git
Password hashes in API responses (use Mongoose toJSON transform)
Estimation edits after round closes (DB-level enforcement)
Returning other experts' estimates while round is open (server filter, not client)
Skip Zod validation (required on BOTH client and server)
Auth logic only in React (must be server-enforced)
JWT in localStorage (use httpOnly cookies)
Massive commits (commit after each step)
Modifying Wideband Delphi methodology

REQUIRED ✅ (Always)

Functional components only (no class components)
asyncHandler() wrapper on all async Express routes
Audit log entry on every mutating operation
Zod validation at client (utils/schemas.ts) AND server (types/api.types.ts)
TypeScript strict mode
Permission check before protected operations
Input sanitization before MongoDB queries
Consistent API response format (see above)
Global error handler (error.middleware.ts) — no unhandled rejections
Inline comments for Wideband Delphi business logic

GIT WORKFLOW

Branch: type/RF###-description
  e.g.: feature/RF001-user-registration
        fix/rounds-estimation-visibility

Commits: conventional format, after EACH logical step
  feat(auth): implement JWT refresh token rotation
  fix(rounds): prevent estimation updates after close
  chore(deps): upgrade mongoose to 8.2.1
  test(statistics): add IQR outlier unit tests

No direct push to main from Phase 2B onwards — PRs required

DEV SETUP

# Frontend
npm install && npm run dev              # :5173

# Backend
cd server && npm install
cp .env.example .env                   # Fill values
npm run dev                            # :4000

# Docker (Phase 2D)
docker-compose up --build              # :3000 frontend, :4000 api, :8025 mailhog

Required .env vars:

PORT=4000 | MONGODB_URI | JWT_ACCESS_SECRET (min 32 chars) | JWT_REFRESH_SECRET (min 32 chars)
JWT_ACCESS_EXPIRY=15m | JWT_REFRESH_EXPIRY=7d | ALLOWED_ORIGINS | RATE_LIMIT_WINDOW_MS | RATE_LIMIT_MAX_REQUESTS

DEBUGGING QUICK REFERENCE

Error	Cause	Fix
JWT invalid signature	Secret mismatch sign/verify	Check .env consistency
CORS blocked	Origin not in ALLOWED_ORIGINS	Add frontend URL to .env
bcrypt.compare → false	Password not hashed on save	Verify User pre-save hook
Expert sees others' estimates	Missing server filter	Filter by userId if round.status === 'open'
Mongoose validation error	Schema mismatch	Check error.errors, verify required fields

ESCALATE TO HUMAN 🛑

Pause and report when encountering:

Architectural changes | Security vulnerabilities | Breaking changes
Business logic ambiguity | Performance trade-offs | External service costs

Format:

🛑 HUMAN DECISION REQUIRED
Context: [what] | Options: A) ... B) ... | Recommendation: [which + why] | Impact: [what breaks]

ACADEMIC PENDING DELIVERABLES (UCE)

Save all diagrams as Mermaid.js to docs/diagrams/ (e.g., class-diagram.mmd, er-diagram.mmd)

Activity diagrams (per use case)
Class diagram
Sequence diagrams
Interaction & deployment diagrams
Normalized ER diagram
Normalized table descriptions + Data dictionary
Interface designs | Quality testing reports

Instructors: Ing. Julio Alexis (Director), Ing. Francisco Santana

CONTEXT FILES (Always reference in IDE)

@AGENTS.md | @types.ts | @server/src/config/constants.ts | @server/src/types/models.types.ts | @server/README.md

Single source of truth. Update when architecture changes.


***

**Next Step:** Guarda esto como `/AGENTS.md` y crea `/.cursorrules` con el mismo contenido (el IDE lo parsea). Reinicia Cursor/Windsurf y valida con: `"Read @AGENTS.md — what is the round lifecycle and why can't estimations be visible before round closes?"`

rules

About