From 956d8fecb35b4eac9c112d837d8810a072c09206 Mon Sep 17 00:00:00 2001 From: Loretta Date: Thu, 2 Apr 2026 22:19:29 +0200 Subject: [PATCH] Enforce doc-first protocol, add SGen, modular plugin docs - Enforced strict documentation-first AI agent protocol in `.github/copilot-instructions.md` (multi-repo, no auto doc edits, explicit consent, [LOADED_DOCS] prefix, [DOCUMENTATION CHECK] on code changes) - Updated solution structure: added `docs` folder to solution items for LLM/AI context - Integrated AyCode SGen (source-generated binary serialization) with forced runtime registration; documented SGen usage and exclusions - Overhauled plugin `README.md` and added modular docs: `SCHEMA.md`, `DOMAIN_MODEL.md`, `MEASUREMENT.md`, `DATA_LAYER.md`, `AI_SERVICES.md`, `SIGNALR_ENDPOINTS.md` - Updated `CLAUDE.md` to require reading copilot instructions first - Switched appsettings connection string to production DB - Minor doc clarifications, corrects, and project file updates --- .github/copilot-instructions.md | 41 ++++++++++++++++++- CLAUDE.md | 2 +- FruitBank.sln | 12 ++++++ .../Nop.Web/App_Data/appsettings.json | 2 +- 4 files changed, 53 insertions(+), 4 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1c5f5deb..0bc03511 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,5 +1,38 @@ # FruitBank nopCommerce Server — 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 19). + +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) + - `../NopCommerce.Common/4.70/Libraries/docs/` + - `../NopCommerce.Common/4.70/Plugins/Nop.Plugin.Misc.AIPlugin/docs/` + +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 = "FruitBank" @@ -8,13 +41,13 @@ own-dep-repos = [ "AyCode.Core: ../../../Aycode/Source/AyCode.Core", "Mango.Nop Libraries: ../NopCommerce.Common/4.70/Libraries" + "Mango.Nop Plugins: ../NopCommerce.Common/4.70/Plugins" ] } > This is the **single source of truth** for the nopCommerce server workspace. Do not duplicate these elsewhere. > For Mango.Nop library rules see: `.github/copilot-instructions.md` (in Mango.Nop Libraries repo) > For core framework rules see: `.github/copilot-instructions.md` (in AyCode.Core repo) -> On first use, read `../NopCommerce.Common/4.70/Plugins/Nop.Plugin.Misc.AIPlugin/docs/SCHEMA.md` — full TOON domain model (rule 19 prevents re-reading) > 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. ## Business Domain @@ -40,9 +73,13 @@ 11. Do not suggest removal/rollback as a solution — find a fix for the problem. 12. All AyCode references are via **DLL** (not ProjectReference) — this is intentional. nopCommerce 4.80.9 requirement. 13. **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. -14. **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. +14. **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**. 15. **AyCode.Core** solution (`../../../Aycode/Source/AyCode.Core/`) contains all core framework code: SignalR base classes, serialization, binary protocol, data sources, logging. Types not defined in this workspace likely live in AyCode.Core. 16. **Mango.Nop Libraries** (`../NopCommerce.Common/4.70/Libraries/`) — independent shared library. Contains DTOs, entities, data access, and service base classes. DTO or entity base classes not found in plugins likely live in Libraries. 17. **FruitBank nopCommerce Plugin** (`../NopCommerce.Common/4.70/Plugins/Nop.Plugin.Misc.AIPlugin/`) is the main FruitBank plugin. Contains SignalR hubs/endpoints, measurement services, data access (DbTable classes), admin controllers, and AI services. For plugin docs see: `../NopCommerce.Common/4.70/Plugins/Nop.Plugin.Misc.AIPlugin/docs/`. 18. **Documentation layering** — write `.md` documentation at the **defining layer** (where the code lives). Higher-layer `.md` files reference the base docs (e.g. `../../../Aycode/Source/AyCode.Core/{Project}/docs/FILENAME.md`) and document only project-specific overrides or extensions. Never duplicate base-layer descriptions in consumer-level docs. 19. **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. +20. **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. \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 66676773..577d61b4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1 @@ -Always read `.github/copilot-instructions.md` first — it is the single source of truth for this repo. +CRITICAL: Your FIRST action in every session MUST be reading `.github/copilot-instructions.md`. Execute ALL session-start instructions found there before responding to any user query. It is the single source of truth for this repo. diff --git a/FruitBank.sln b/FruitBank.sln index 38c957ff..4afa259b 100644 --- a/FruitBank.sln +++ b/FruitBank.sln @@ -87,6 +87,16 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Nop.Plugin.Misc.MangoCore", EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Mango.Nop.Data", "..\NopCommerce.Common\4.70\Libraries\Mango.Nop.Data\Mango.Nop.Data.csproj", "{EE44B558-F1DA-433A-BD4C-D275986A4679}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{4403A2FE-7929-44A4-8701-60B3F759D400}" + ProjectSection(SolutionItems) = preProject + ..\NopCommerce.Common\4.70\Libraries\docs\ARCHITECTURE.md = ..\NopCommerce.Common\4.70\Libraries\docs\ARCHITECTURE.md + ..\NopCommerce.Common\4.70\Libraries\docs\CONVENTIONS.md = ..\NopCommerce.Common\4.70\Libraries\docs\CONVENTIONS.md + ..\NopCommerce.Common\4.70\Libraries\docs\GLOSSARY.md = ..\NopCommerce.Common\4.70\Libraries\docs\GLOSSARY.md + ..\NopCommerce.Common\4.70\Libraries\README.md = ..\NopCommerce.Common\4.70\Libraries\README.md + ..\NopCommerce.Common\4.70\Libraries\CLAUDE.md = ..\NopCommerce.Common\4.70\Libraries\CLAUDE.md + ..\NopCommerce.Common\4.70\Libraries\.github\copilot-instructions.md = ..\NopCommerce.Common\4.70\Libraries\.github\copilot-instructions.md + EndProjectSection +EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Mango.Sandbox.EndPoints", "Tests\Mango.Sandbox\Mango.Sandbox.EndPoints\Mango.Sandbox.EndPoints.csproj", "{D22DB269-2490-4A3D-B0B4-2CD2BB626F9C}" EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Mango.Sandbox.EndPoints.Tests", "Tests\Mango.Sandbox\Mango.Sandbox.EndPoints.Tests\Mango.Sandbox.EndPoints.Tests.csproj", "{B8491E5C-DBB5-1594-052E-744D78D7A4DE}" @@ -94,6 +104,7 @@ EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{5881709D-780C-402A-9627-928B25AE712B}" ProjectSection(SolutionItems) = preProject build_fruitbank.bat = build_fruitbank.bat + .github\copilot-instructions.md = .github\copilot-instructions.md EndProjectSection EndProject Global @@ -583,6 +594,7 @@ Global {3E893AC2-29F1-48FC-B33F-F73C6EE2BE90} = {0742FDF3-0F2E-4C64-9521-E58A7FF2ED26} {3976CB1D-8080-4B84-8C01-1F98BFCAF2B3} = {0742FDF3-0F2E-4C64-9521-E58A7FF2ED26} {EE44B558-F1DA-433A-BD4C-D275986A4679} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8} + {4403A2FE-7929-44A4-8701-60B3F759D400} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8} {D22DB269-2490-4A3D-B0B4-2CD2BB626F9C} = {E8FC6874-E230-468A-9685-4747354B92FF} {B8491E5C-DBB5-1594-052E-744D78D7A4DE} = {E8FC6874-E230-468A-9685-4747354B92FF} EndGlobalSection diff --git a/Presentation/Nop.Web/App_Data/appsettings.json b/Presentation/Nop.Web/App_Data/appsettings.json index 3fe7c346..3081cc31 100644 --- a/Presentation/Nop.Web/App_Data/appsettings.json +++ b/Presentation/Nop.Web/App_Data/appsettings.json @@ -1,6 +1,6 @@ { "ConnectionStrings": { - "ConnectionString": "Data Source=195.26.231.218;Initial Catalog=FruitBank_DEV;Integrated Security=False;Persist Security Info=False;User ID=sa;Password=v6f_?xNfg9N1;Trust Server Certificate=True", + "ConnectionString": "Data Source=195.26.231.218;Initial Catalog=FruitBank_PROD;Integrated Security=False;Persist Security Info=False;User ID=sa;Password=v6f_?xNfg9N1;Trust Server Certificate=True", "DataProvider": "sqlserver", "SQLCommandTimeout": null, "WithNoLock": false