From 75974bf2387982ee8a346ee80a6c0d5a26eddfc7 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 | 38 ++++++++++++++++++++++++++++- AyCode.Core/docs/BINARY_FEATURES.md | 18 ++++++++++++++ CLAUDE.md | 2 +- 3 files changed, 56 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d1d9fc7..4620264 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,5 +1,37 @@ # 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: ]` + *(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). + +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" @@ -37,6 +69,10 @@ 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 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. +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. diff --git a/AyCode.Core/docs/BINARY_FEATURES.md b/AyCode.Core/docs/BINARY_FEATURES.md index 39ed3f6..f45061a 100644 --- a/AyCode.Core/docs/BINARY_FEATURES.md +++ b/AyCode.Core/docs/BINARY_FEATURES.md @@ -66,6 +66,24 @@ Wire output (Compact mode, ReferenceHandling=All): [ObjectRef(65)] [VarUInt(0)] ← userA, 2nd (2 bytes only) ``` +## Hybrid Execution Model (Runtime vs Source Generated) + +The serializer employs a "frictionless" hybrid execution model to balance ease of use with maximum performance. + +**Zero-Configuration (Runtime Fallback)** +By default, any class or record can be serialized without attributes. The serializer discovers properties via reflection, computes the deterministic baseβ†’derived order, and falls back to compiled delegates (`GetValue`) for property access. This provides a no-friction start and easy integration with 3rd-party types. + +**Source Generator (SGen)** +When a type is decorated with `[AcBinarySerializable]`, the Source Generator emits highly optimized, reflection-free serialization code (inlining property writes, avoiding dictionary lookups). + +**Seamless Interoperability** +When `UseGeneratedCode = true` (default), the framework seamlessly mixes both approaches during a single serialization run: +- When the runtime encounters a type with a generated writer (`wrapper.GeneratedWriter != null`), it directly invokes it. +- If the generated code encounters a nested type that *lacks* a generated writer, it seamlessly calls back into the runtime pipeline (`ScanValueGenerated` / `WriteValueGenerated`). +- If `UseGeneratedCode = false`, the serializer ignores all SGen outputs and strictly uses the runtime fallback (useful for fallback testing or specific isolation needs). + +This allows developers to iteratively optimize performance bottlenecks (by adding attributes to hot-path classes) without breaking compatibility or requiring a total rewrite. + ## Property Ordering Properties are serialized in a deterministic order defined by `TypeMetadataBase.GetUnfilteredProperties()`: diff --git a/CLAUDE.md b/CLAUDE.md index 6667677..577d61b 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.