From d5fdd57ddde83a199b48490b8b3fc1f4a5cbca12 Mon Sep 17 00:00:00 2001 From: Loretta Date: Thu, 2 Apr 2026 09:02:54 +0200 Subject: [PATCH] Enforce strict AI agent protocol, doc sync, and glossary - Added "AI AGENT CORE PROTOCOL" to all copilot-instructions.md files: mandates [LOADED_DOCS] prefix, hard-gates tool usage, enforces no-re-read of .md files, and requires user consent for doc/code changes. - Updated CLAUDE.md to require reading copilot-instructions.md first. - Added topic-based doc separation and folder navigation rules. - Changed doc sync: agent now passively detects discrepancies and asks before updating docs. - Every code-modifying response must end with a [DOCUMENTATION CHECK] section. - Centralized measurement system and domain traps in new FruitBank.Common/docs/GLOSSARY.md; updated references in FruitBankHybridApp GLOSSARY.md. - Clarified schema and doc locations in FruitBankHybridApp README.md. - Added hybrid execution model section to AyCode.Core BINARY_FEATURES.md. - Removed unnecessary BeginUpdate/EndUpdate calls in MgGridBase.cs for layout persistence. - Removed full Toon schema from plugin SCHEMA.md to avoid duplication. --- .github/copilot-instructions.md | 39 +++++++++++++++++-- .../Components/Grids/MgGridBase.cs | 7 +--- CLAUDE.md | 2 +- 3 files changed, 38 insertions(+), 10 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 09aefa7..ee737ee 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,5 +1,34 @@ # AyCode.Blazor — 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: ]` + *(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 15). + +3. **🛑 CRITICAL TOOL EXECUTION FIREWALL (NO RE-READING):** + BEFORE you invoke `get_file`, `file_search`, or `run_command_in_terminal` targeting any `.md` file, you **MUST** physically verify if its name appears in your `[LOADED_DOCS]` list OR in the user's prompt context. + - **IF YES (IT IS CACHED):** You are **HARD-LOCKED** from using any tool to read or search it again. You must extract the answer STRICTLY from your existing context memory. + - **PENALTY:** Using a tool to re-read an already mapped `.md` file causes catastrophic context duplication and wastes resources. Treat `[LOADED_DOCS]` as an absolute firewall blocking all further file reads for those specific files. + +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 # own-dep-repos: "name: path" — paths are relative to this repo root (.github/..) @repo { name = "AyCode.Blazor" @@ -32,10 +61,14 @@ 10. Do not suggest removal/rollback as a solution — find a fix for the problem. 11. All DLL references to AyCode.Core projects are via `DllReference` (not ProjectReference) — this is intentional, required for build isolation and nopCommerce plugin compatibility in consuming projects. 12. **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. -13. **Keep all .md files in sync** — when you modify code and you know which .md file documents it, update that .md file too. If you notice a contradiction between code and an .md file, automatically update the .md to match the code (code is the source of truth). When fixing a reference, check other .md files that may share the same broken reference. If the root cause is at a lower layer, fix it there first. During code review, if you find useful behavior or conventions not yet documented, briefly suggest what to document and where — but do not add new content without approval. +13. **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**. 14. **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. 15. **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. +16. **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. ## Related Solutions -15. **AyCode.Core** solution (`../AyCode.Core/AyCode.Core.sln`) contains all core framework code (SignalR, serialization, data sources, base classes, interfaces). Types referenced in this Blazor solution but not defined here (e.g. `AcSignalRDataSource`, `AcBinaryHubProtocol`, `IId`, `AcObservableCollection`, `AcLoggerBase`) likely live in AyCode.Core. -16. For AyCode.Core domain rules see: `../AyCode.Core/.github/copilot-instructions.md` +17. **AyCode.Core** solution (`../AyCode.Core/AyCode.Core.sln`) contains all core framework code (SignalR, serialization, data sources, base classes, interfaces). Types referenced in this Blazor solution but not defined here (e.g. `AcSignalRDataSource`, `AcBinaryHubProtocol`, `IId`, `AcObservableCollection`, `AcLoggerBase`) likely live in AyCode.Core. +18. For AyCode.Core domain rules see: `../AyCode.Core/.github/copilot-instructions.md` diff --git a/AyCode.Blazor.Components/Components/Grids/MgGridBase.cs b/AyCode.Blazor.Components/Components/Grids/MgGridBase.cs index 6a5c20a..afa0314 100644 --- a/AyCode.Blazor.Components/Components/Grids/MgGridBase.cs +++ b/AyCode.Blazor.Components/Components/Grids/MgGridBase.cs @@ -770,13 +770,10 @@ public abstract class MgGridBase