AyCode.Core/.github/copilot-instructions.md

AyCode.Core — Domain Rules

🛑 AI AGENT CORE PROTOCOL (CRITICAL ENFORCEMENT)

You are operating in a multi-repo, documentation-first architecture. You MUST STRICTLY follow this protocol for every response. Failure to do so will break the workspace rules.

1. MANDATORY OUTPUT PREFIX: Your response MUST begin exactly with this format on the very first line: [LOADED_DOCS: <comma-separated list of .md files currently in your context>] (If no .md files are loaded yet, write [LOADED_DOCS: NONE].)

2. HARD-GATE DELAY (DOCS BEFORE CODE) & TOOL EXECUTION BLOCK:

   • If [LOADED_DOCS: NONE] applies, you MUST STOP and you are STRICTLY FORBIDDEN to use the following tools: code_search, get_symbols_by_name, find_symbol, or get_file (for non-markdown files).
   • Your VERY FIRST AND ONLY allowed tool calls must be file_search or get_file targeting the .md documentation in the relevant docs/ folders or README.md.
   • Do not answer the user's core question until the [LOADED_DOCS] list is populated with the base architecture files.
   • CRITICAL EXCEPTION: Do NOT re-read .md files that are already mapped in your context or LOADED_DOCS list (strictly maintain rule 20).
   • CROSS-REPO HARD-GATE: When navigating to an external repo (via own-dep-repos paths), read that repo's docs/ and README.md BEFORE searching its source code. The hard-gate applies to EVERY repo you enter, not just your own.

3. STRICT NO-RE-READ POLICY (ANTI-LOOP): You are PHYSICALLY FORBIDDEN from calling get_file or file_search on any .md file that is already listed in your [LOADED_DOCS] prefix.

   • Once an .md file is in your context, it STAYS in your context.
   • Re-reading them wastes tokens and breaks the protocol.
   • ONLY re-read an .md file if the user EXPLICITLY states "the file has changed on disk, read it again".
   • If the user simply mentions a glossary term or requests info found in a loaded doc, answer directly from memory. DO NOT search for it again.

4. CONTEXT RECOVERY (SMART READ): If the user asks a domain/architecture specific question and you realize the essential .md files are NO LONGER in your current context (they dropped out of memory), you MUST automatically re-read the necessary documentation before answering. Do NOT wait for the user to explicitly tell you to re-read them. Prioritize scanning the docs/ folders to recover the lost context.

   Directories to read (when recovering context):

   • docs/ (in this repository root)

5. EXPLICIT CONSENT FOR MODIFICATIONS: NEVER rewrite, create, or delete code/files without the user's explicit permission. If the user does not specifically request a code modification (e.g., using phrases like "we are just thinking," "what do you think," "let's plan"), you MUST ONLY provide text-based analysis and planning. You are FORBIDDEN from using file-modifying tools (replace_string_in_file, edit_file, create_file, etc.) until the user explicitly says "ok", "go ahead", "implement", or a similar unambiguous approval.

Workspace Dependencies

@repo { name = "AyCode.Core" type = "framework" layer = 0 own-dep-repos = [] }

This is the single source of truth for domain rules. Do not duplicate these elsewhere. For detailed docs see: README.md → docs/ External repos in own-dep-repos are fully accessible — read their source code, docs, and .github/copilot-instructions.md freely when you need type definitions, base classes, or context. Do not limit yourself to the current workspace.

Key Abstractions

1. IId is the foundation interface — almost every entity implements it. Always preserve ID integrity.
2. Generic entity hierarchy: Interfaces (AyCode.Interfaces) → Entities (AyCode.Entities) → Models (AyCode.Models). Entities are abstract generics; concrete types live in consuming projects.
3. TrackingState enum (Added/Modified/Deleted/Unchanged) drives client-side change tracking, not EF Core.

Serialization

4. Toon (Token-Oriented Object Notation) — primary goal is LLM accuracy. @meta/@data sections.
5. AcBinary — primary goal is speed. Two-phase scan+serialize, reference tracking, string interning.
6. AcJson — Newtonsoft.Json wrapper with $id/$ref, IId-based reference resolution, and chain API.

SignalR

7. Tag-based transport (no conventional hub methods) — SignalR communication should generally use the generic methods provided by AcWebSignalRHubBase (server) and AcSignalRClientBase (client). Request types are conventionally identified by int tags. Try to avoid adding custom, business-specific, or conventional string-based Hub methods (e.g., GetUsers()).
8. AcSignalRDataSource — generic IList<T> with change tracking, CRUD via SignalRCrudTags, binary merge, rollback. See AyCode.Services.Server/docs/SIGNALR_DATASOURCE.md. Transport docs: AyCode.Services/docs/SIGNALR.md.
9. JSON-in-Binary tech debt — client→server request parameters are currently JSON inside a Binary envelope (SignalPostJsonDataMessage). Do NOT attempt to fix as a side effect — requires coordinated changes across all consuming projects.

Critical Warnings

10. PasswordHasher — PBKDF2-HMAC-SHA512. Do NOT modify the salt logic or iteration count — existing passwords become unverifiable.
11. MeasuringStatus.Finnished — intentional legacy typo in consuming projects. Do NOT fix the spelling.
12. LogLevel enum values — synchronized with database. Do NOT renumber.

Conventions

13. Do not suggest removal/rollback as a solution — find a fix for the problem.
14. Extension methods over instance methods for CRUD operations.
15. Session pattern for reads, Transaction pattern for writes.
16. Target framework is net9.0 (set in AyCode.Core.targets). The SourceGenerator targets netstandard2.0. Consuming projects (AyCode.Blazor, FruitBankHybridApp UI) may target net10.0 but reference AyCode.Core DLLs built as net9.0.
17. No redundant code — before writing new logic, check whether similar methods already exist in the current context. Reuse or extract shared logic into smaller methods rather than duplicating. If an existing method does most of what you need, split it into composable parts.
18. Keep all .md documentation in sync (PASSIVE DETECTION & ASK FIRST) — If you notice any contradiction, error, or missing information between the code and your currently loaded .md files, briefly notify the user and ask for permission before making changes. Do NOT automatically update .md files or trigger new searches yet. Once the user approves, you may actively search, read, and update the necessary docs in the correct layer. Identify missing documentation: If you notice during your task that a frequently used pattern, underlying logic, or important behavior is missing from the docs, and adding it would improve future LLM context-efficiency (saving searches/tokens), briefly notify the user to get approval. Topic-based separation: When creating or expanding documentation, keep logically distinct features or domains in separate .md files (e.g., architecture, data model, billing) and only reference them in the main/index documents. Do not cram everything into a single monolithic file. Keep in mind: these .md files are primarily for LLM grounding and context providing. Keep them concise, structured, and focused on rules/patterns rather than human-readable prose. ENFORCEMENT: At the end of EVERY code-modifying response, append a [DOCUMENTATION CHECK] section. Evaluate ONLY the .md files already in your context. State in 1-2 sentences if you found discrepancies or missing concepts, and ask if they should be documented. DO NOT trigger searches or tool calls for this initial check.
19. Documentation layering — write .md documentation at the defining layer (where the code lives). Higher-layer .md files reference the base docs (e.g. see AyCode.Core/docs/SIGNALR.md) and document only project-specific overrides or extensions. Never duplicate base-layer descriptions in consumer-level docs.
20. Do not re-read .md files already in your context window. They only change if you modify them yourself (new content is already in context) or if the developer tells you they changed — in that case re-read them once.
21. Folder navigation — start from the root README.md for solution-level navigation. When you need to understand a folder's contents or find a type/class, read the README.md in that folder first — it indexes the local files and sub-folders. Follow this before grepping or reading source files.