Plataforma-de-desarrolladores/AGENTS.md

AGENTS.md

Project identity

This project is Plataforma de Desarrolladores Agua Hillo.

It is an ASP.NET WebForms application using C# and .NET Framework 4.8 or 4.8.1.

Do not convert this project to:

• ASP.NET Core
• Razor Pages
• MVC Core
• Blazor
• Minimal APIs
• Angular-only app
• Web API-only app

ASP.NET WebForms must stay on .NET Framework. If a command, package, or template requires ASP.NET Core, do not use it for this project.

---

Main goal

Create a clean WebForms starter project from zero, keeping the same Metronic visual style and only the necessary bundle methods used by the master page and login page.

The project must use a contract/service structure so pages, master page, login, menu, user session, and future modules do not connect directly to database classes.

Target architecture:

ASPX / Master Page / User Controls
    ↓
Contracts
    ↓
Services
    ↓
Repositories / SQL helpers
    ↓
Database

---

Language rules

• All new code must be C#.
• All new project-owned identifiers and file names must use Spanish domain terminology. This includes file names, namespaces, classes, interfaces, methods, properties, fields, parameters and local variables in C#; JavaScript functions and variables; CSS hooks; HTML data-* attributes; and ViewState keys. Keep framework, library, protocol, generated-code, and established external API names unchanged.
• Do not introduce English aliases for Spanish database or business concepts. For example, use CveUnidadMedida, unidadMedida, or data-cve-unidad-medida, not MeasurementUnit, measurementUnit, or data-measurement-unit-id.
• Do not add VB.NET files.
• Do not add .vb files to the active project.
• Old VB files may exist only as migration reference files using .vb.txt.
• Do not use VB comment syntax in C# files.
• Do not use JavaScript/CSS/Powershell comments as C# comments.

---

Terminología de usuarios y asociado CANADEVI

• Los usuarios que no son clientes se denominan usuarios de Agua de Hermosillo o mojados.
• Sólo los usuarios de Agua de Hermosillo (mojados) pueden activar o desactivar Asociado CANADEVI en el registro de un desarrollador. Los usuarios clientes pueden consultar ese dato, pero no modificarlo. La restricción debe aplicarse también en servidor al guardar, no sólo en la interfaz.

Source code readability rules

All generated or modified source code must be formatted for human maintenance.

• Do not compress multiple controls, HTML elements, CSS rules, SQL clauses, assignments, conditions, or statements onto one line merely to reduce file length.
• Use consistent indentation and line breaks that make nesting and control flow visible.
• Put independent C# statements on separate lines. Expand non-trivial if, loops, object initializers, method calls, and methods across multiple lines.
• In ASPX/HTML, place nested elements and server controls on separate indented lines. Keep attributes readable; wrap long declarations across lines.
• Format CSS with one declaration per line for page-specific styles. Format JavaScript and SQL using the same readability principle.
• Prefer clear diffs and easy future editing over compact generated output.
• The command rule requiring one-line PowerShell or terminal commands applies only to commands. It does not apply to C#, ASPX, HTML, CSS, JavaScript, SQL, XML, or configuration source.

Agent instruction file maintenance rules

• Before modifying AGENTS.md or any complementary AGENTS_*.md file, read the existing file and apply only the smallest required addition or correction.
• Do not rewrite or replace an entire agent instruction file unless the user explicitly requests a complete rewrite.
• Preserve existing user-authored rules, terminology, capitalization, examples, and formatting outside the requested change.
• When adding a rule, first verify whether an equivalent or conflicting rule already exists and update only the relevant section.

Mandatory authorization and change-control rules

• The agent is permanently prohibited from executing git commit, git commit --amend, creating commits through another command, or asking another agent to create a commit in this repository.
• Before modifying code, files, configuration, stored procedures, database schema, or database data, the agent must tell the user exactly which files and objects it proposes to change and what each change will do.
• The agent must wait for the user's explicit confirmation before making any modification.
• Until explicit confirmation is received, the agent may perform read-only inspection and diagnosis only.
• Authorization to inspect, diagnose, or review does not authorize implementation.
• Authorization is limited to the files and objects explicitly disclosed. If the proposed scope changes, the agent must explain the additional changes and obtain new explicit confirmation.
• Authorization to edit a SQL script does not authorize installing or executing it against a database. Database execution requires separate explicit confirmation.
• A corrective action, rollback, or attempted restoration is still a modification and also requires explicit confirmation before execution.
• The agent must never infer authorization from urgency, prior approval for a different change, or the fact that the agent caused the problem.

Mandatory complementary instruction files

• Antes de trabajar en cada solicitud del proyecto, leer AGENTS.md y los agentes complementarios aplicables. Nunca omitirlos al corregir errores o reutilizar código existente; verificar también el código que se conserva.
• El CSS y JavaScript específicos de una página .aspx deben permanecer dentro de ese mismo .aspx: CSS en un bloque <style> de la sección H y JavaScript en un bloque <script> de la sección J. No crear archivos .css o .js separados para esa página ni trasladar su código a bundles globales, salvo petición explícita del usuario. Esta regla no cambia la carga global de recursos compartidos y de UserControls.
• Los archivos CSS/JS de controles y UserControls deben cargarse globalmente desde Styles/ y Scripts/, mediante los bundles de la master, aunque el control no esté presente. No usar Page.Header.Controls.Add ni inyectar archivos o definiciones CSS/JS desde el control. Para acciones puntuales desde el servidor, usar el RegistraScript existente (PageScriptRegistrar.RegistraScript en UserControls); no inventar colas ni serializar acciones como alternativa.
• Cada instancia de un componente debe marcar su inicialización JavaScript con un atributo data-* propio. Inicializar sólo elementos sin marca, sin quitar y volver a agregar eventos. Aplican las reglas de AGENTS_WEBFORMS_ESTRUCTURA.md y AGENTS_JAVASCRIPT_INITIALIZATION.md.

The following files are part of these instructions. Read each file whose scope applies before taking action:

• AGENTS_ARQUITECTURA.md: project structure, contracts, services, repositories, models, database access, and transactions.
• AGENTS_WEBFORMS_ESTRUCTURA.md: WebForms pages, master page, login, bundles, assets, configuration, controls, and application shell.
• AGENTS_MANTENIMIENTO_PROYECTO.md: commands, security, errors, feedback, grids, delivery, checklist, and project evolution.
• AGENTS_STORED_PROCEDURES.md: stored-procedure rules.
• AGENTS_DATA_READER_MAPPING.md: database-result mapping.
• AGENTS_DATABASE_ERROR_LOGGING.md: database error diagnostics.
• AGENTS_PAGE_STRUCTURE.md: page locations and structure.
• AGENTS_WEBFORMS_PARTIAL_POSTBACKS.md: forms, ScriptManager, UpdatePanel, and partial postbacks.
• AGENTS_JAVASCRIPT_INITIALIZATION.md: idempotent JavaScript initialization.
• AGENTS_CATALOG_STRUCTURE.md: catalog layout and behavior.
• AGENTS_DOCUMENT_STORAGE.md: protected document storage and retrieval.

What not to add yet

Do not add the following until the user explicitly asks:

• Real SQL login implementation
• Full permission system
• Notifications
• Web Push
• PDF viewer
• BuscadorCatalogo
• DropdownGrid
• PorcentajeBox
• Angular
• APIs
• Background jobs
• OWIN
• Entity Framework
• Dependency injection framework
• New Metronic version

The starter must stay small and focused: commands, master page, login, contracts, dummy user session, bundle structure, copied assets, and centralized SQL foundation.

---

REGLA OBLIGATORIA: Nunca usar args.get_panelsUpdated() ni get_panelsUpdated() en JavaScript de WebForms/UpdatePanel de este proyecto; esa llamada rompe repetidamente el entorno. Para reinicializar después de postbacks parciales usar PageRequestManager.add_endRequest(function () { ... }) sin depender de args, o eventos delegados cuando corresponda.