AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md

# LLM Protocol Decisions

Append-only log of decisions about the AI AGENT CORE PROTOCOL and related LLM tooling (skills, instruction files, shared conventions) across the 8 known `.github/copilot-instructions.md` files.

---

## Current protocol state (quick reference)

Active as of **2026-04-24**. For the full evolution history, see the dated table near the bottom of this file. Read this summary first to orient yourself before diving into the dated entries.

**Session start flow**:
- **Primary files**: agent reads `copilot-instructions.md` + 3 SKILL.md files (`docs-discovery`, `docs-check`, `protocol-audit`). First response's `[LOADED_DOCS: ...]` shows 4 files.
- **Inherit files**: agent reads this inherit `copilot-instructions.md` + AyCode.Core's canonical `copilot-instructions.md` (for the numbered rules) + 3 SKILL.md files. First response's `[LOADED_DOCS: ...]` shows 5 files.
- **Why pre-load**: workspace skills are NOT in Claude Code's native skill-registry; pre-loading ensures implicit triggers fire reliably.

**AI AGENT CORE PROTOCOL** (present verbatim in each primary `.github/copilot-instructions.md`):
1. **MANDATORY OUTPUT PREFIX** — every response starts with `[LOADED_DOCS: N files (+K this turn: <short names>)]`. Short-name rule: basename by default; `TOPIC/README.md` for topic-folder READMEs (to disambiguate the many `README.md` files); extend upward for cross-project collisions. Never emit a bare `README.md` in the prefix.
2. **HARD-GATE: DOCS BEFORE CODE** — no `code_search` / source `get_file` until relevant `.md` docs are loaded. Includes **CROSS-REPO HARD-GATE** (applies to every repo entered via `own-dep-repos`) and **PER-QUESTION DOC-FIRST** (check for unloaded `.md` before grepping code).
3. **STRICT NO-RE-READ POLICY** — a doc is "in context" only if actually read via tool call in THIS conversation (session summaries / memory entries do NOT count — lossy compression).
4. **CONTEXT RECOVERY** — auto-detection triggers: session starts with a summary, mid-session compaction, or inability to quote exact content → reset `[LOADED_DOCS: NONE]` and re-read per Rule #2.
5. **EXPLICIT CONSENT FOR MODIFICATIONS** — no rewriting, creating, or deleting *any* file (code, docs, config, memory, or otherwise) without explicit user approval.

**Docs layout — Option C "folder + topic-prefixed companions"**:
- Paired topics live in `TOPIC/` folders: `TOPIC/README.md` (main, canonical) + `TOPIC/TOPIC_ISSUES.md` + `TOPIC/TOPIC_TODO.md` + optional `TOPIC/TOPIC_<subname>.md`.
- Single-file reference docs (`ARCHITECTURE.md`, `CONVENTIONS.md`, `GLOSSARY.md`, `DTOS.md`, etc.) remain flat at the `docs/` root.
- Each `docs/` root has a `README.md` index listing the topics.
- Project-specific variants of framework topics (e.g., the server-side logger in `AyCode.Core.Server`, the Nop bridge in `Mango.Nop.Services`) get their own `TOPIC/README.md` under the variant project's `docs/`.
- `.csproj` files use recursive glob: `<None Include="docs\**\*.md" />` so Pattern B nesting auto-shows in Visual Studio Solution Explorer without manual entries.

**Instruction files — 8 total**:
- **5 primary** files contain the full numbered AI AGENT CORE PROTOCOL: `AyCode.Core`, `AyCode.Blazor`, `Libraries`, `FruitBank` (Mango/Source), `FruitBankHybridApp`.
- **3 inherit** files reference AyCode.Core's protocol via blockquote (no duplicated numbered rules): `Mango.Nop.Core` (sub-project framework), `Nop.Plugin.Misc.AIPlugin` (plugin source), `Mango.FruitBank` (nopCommerce deployment host).
- Each non-Core file has `## Shared Agent Skills` + `## Protocol History` sections.

**Issue / TODO / Decision ID format** (globally unique):
- Format: `{TOPIC}-{TYPE}-{N}` (e.g., `LOG-I-5`, `SIG-T-3`, `BIN-B-1`, `XCUT-I-1`, `LLMP-DEC-4`)
- **Topic codes**: `LOG` (logger), `SIG` (SignalR), `SBP` (SignalR binary protocol), `BIN` (binary serializer), `TOON` (Toon serializer), `GRID` (MGGRID), `XCUT` (cross-cutting), `LLMP` (LLM-protocol meta — uses `DEC` type only).
- **Type codes**: `I` = issue, `T` = TODO, `B` = bug, `C` = critical (severity override), `DEC` = decision (LLMP-only).
- **Counter scope**: per (topic, type) pair. `LOG-I-1` and `LOG-T-1` independent.
- **Append-only**: IDs never change once assigned. Full registry + rules: `AyCode.Core/.github/skills/docs-check/references/TOPIC_CODES.md`.

**Agent skills — all three at `AyCode.Core/.github/skills/`**:
- **`docs-discovery`** — extracts topic tokens from user requests, globs `**/docs/TOPIC/**/*.md` (+ companion patterns), loads the paired main+ISSUES+TODO set before source-code search. Updates LOADED_DOCS via Rule #1 format.
- **`protocol-audit` v2.2** — reads `references/REPOS.md` and audits all 8 instruction files: Common invariants C1-C4 for all (C4 = `## Session Setup` presence, added in LLMP-DEC-33); Primary-only (P1-P10) for the 5 primary; Inherit-only (I1-I3) for the 3 inherit; Cross-cutting (X1, X3) for primary, (X1, X2) for non-Core primary, (X1, X2) for inherit. Reports PASS/FAIL per invariant-file cell, with patch suggestions. Does NOT auto-apply patches.
- **`docs-check` v1.0** — end-of-code-modifying-response skill: evaluates loaded `.md` for drift vs code, missing topic coverage, csproj-glob registration gaps, and new issue/TODO candidates. Emits the `[DOCUMENTATION CHECK]` section (or `[DOCUMENTATION CHECK] None.` single-line). Read-only on loaded docs; all patches as proposals per Rule #5.

**Docs-sync enforcement (`[DOCUMENTATION CHECK]` at end of code-modifying responses)**:
- **Keep all .md in sync** — if code and loaded docs disagree, notify and ask (do NOT silently edit).
- **Identify missing documentation** — if a frequently-used pattern isn't documented in main topic docs, propose an entry.
- **Topic-based separation** — split logically distinct topics into separate `.md` files; keep concise and LLM-oriented.
- **File registration (scope: outside existing glob only)** — if a new `.md` falls outside the nearest `.csproj`'s recursive globs (`docs\**\*.md`, `**\README.md`), surface the needed glob patch. Common case (doc under `docs/`, folder-README) is zero-cost via csproj globs set up cluster-wide.
- **Issue / TODO surfacing** — surface concrete, non-duplicate, actionable `_ISSUES.md` / `_TODO.md` candidates as draft entries (priority P1-P3, rationale, code ref — **NO ID**, user assigns at apply-time). **Prerequisites (ALL must hold):** companion is in `LOADED_DOCS`; high-confidence (quotable evidence); concrete; not duplicate. **Max 3 items per response.** Also: surface `Status: FIXED` suggestions when a listed issue is fixed in the current response.
- **Empty-state output** — if `[DOCUMENTATION CHECK]` has nothing to report: `[DOCUMENTATION CHECK] None.` single line, no padding.

**Decision Log governance (this file)**:
- **Append-only.** Never rewrite or delete entries. Reversals and refinements get *new* entries that reference the superseded one by ID (e.g., "LLMP-DEC-26 superseded by LLMP-DEC-27").
- **Entries have `LLMP-DEC-N` IDs** (topic=LLMP, type=DEC — see TOPIC_CODES.md). Sequential, append-only, never renumber. Reference entries by ID for unambiguous citation from code comments, other `.md` files, or cross-repo.
- **Archive annually** once the log reaches ~50 entries (split to `LLM_PROTOCOL_DECISIONS_<year>.md`). IDs stay unique across archives.
- **`Affected` column** uses the scope codes defined below.
- **User consent required** for every new entry.

---

## Purpose

Quick lookup for **why** a rule is the way it is, to avoid:
- Re-debating decisions that were already discussed and resolved
- Silently "optimizing away" a rule whose edge-case purpose is no longer obvious
- Losing context between sessions / across team members

## Scope

**Tracked here:**
- `.github/copilot-instructions.md` rule additions / removals / rewordings
- `CLAUDE.md` changes
- New, modified, or removed agent skills (`docs-discovery`, `protocol-audit`, etc.)
- Protocol-level structural shifts (doc layout, file location conventions)

**NOT tracked here:**
- Code refactors or feature work — use commit messages / PR descriptions
- Code-architecture decisions — see `docs/ARCHITECTURE.md` at the relevant layer
- Trivial fixes (typos, path corrections without rule-semantic change)

## Writing rules

1. **Append-only.** If a decision is reversed or superseded, add a NEW entry that points to the old one. Do not rewrite history — the evolution itself is informative.
2. **One row per decision.** Keep the rationale concise; the purpose is scan-ability, not prose.
3. **`Affected` column** uses the scope codes defined below — always be explicit about which files were touched.
4. **Explicit consent required for additions** (per Rule #5 of the active `copilot-instructions.md`). The LLM proposes the entry; the user reviews and approves before the write.
5. **Reference this log** before proposing a protocol change — if the change was already discussed, the existing entry may save a debate.

## Scope codes (for the `Affected` column)

| Code                   | Meaning                                                                                                   |
|------------------------|-----------------------------------------------------------------------------------------------------------|
| `5× primary`           | All 5 primary `copilot-instructions.md` (AyCode.Core, AyCode.Blazor, Libraries, FruitBank, FruitBankHybridApp) |
| `4× non-Core primary`  | The 4 primary files except AyCode.Core                                                                    |
| `3× inherit`           | The 3 inherit files (Mango.Nop.Core, Nop.Plugin.Misc.AIPlugin, Mango.FruitBank)                           |
| `all 8`                | All 8 files: 5 primary + 3 inherit                                                                        |
| `<repo>/...`           | A single specific file path                                                                               |
| `<skill-name>/...`     | Skill directory under `.github/skills/`                                                                   |

The "primary" vs "inherit" distinction is defined in `protocol-audit/references/REPOS.md`.

## 2026

| ID            | Date       | Decision                                              | Rationale                                                                                         | Affected                                                                    |
|---------------|------------|-------------------------------------------------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| LLMP-DEC-1    | 2026-04-20 | Added CROSS-REPO HARD-GATE to Rule #2                 | Docs-before-code was applied only to the own repo, not external deps                              | `5× primary`                                                                |
| LLMP-DEC-2    | 2026-04-20 | Added PER-QUESTION DOC-FIRST to Rule #2               | LLM skipped checking for relevant `.md` before jumping to code search                             | `5× primary`                                                                |
| LLMP-DEC-3    | 2026-04-21 | Expanded Rule #5 scope: "code/files" → "any file..."  | Memory / config / docs edits also need consent; old wording too narrow                            | `5× primary`                                                                |
| LLMP-DEC-4    | 2026-04-22 | Added Auto-detection triggers to Rule #4              | "realize" was subjective; post-compaction reset to `[LOADED_DOCS: NONE]` didn't fire reliably     | `5× primary`                                                                |
| LLMP-DEC-5    | 2026-04-22 | Added "in context" definition to Rule #3              | Summary content was mistaken for actually-loaded docs (lossy compression)                         | `5× primary`                                                                |
| LLMP-DEC-6    | 2026-04-22 | Unified AyCode.Blazor Rule #3 with the other 4 repos  | Was custom "CRITICAL TOOL EXECUTION FIREWALL" variant; normalized                                 | `AyCode.Blazor/copilot-instructions.md`                                     |
| LLMP-DEC-7    | 2026-04-22 | "strictly maintain rule X" → "rule 3"                 | Per-repo numbers varied (15/18/19/20/21); unified reference                                       | `5× primary`                                                                |
| LLMP-DEC-8    | 2026-04-22 | Created `protocol-audit` skill at repo-level          | Cross-repo consistency check; `.github/skills/` chosen over personal paths (DRY)                  | `protocol-audit/SKILL.md` + `protocol-audit/references/REPOS.md`            |
| LLMP-DEC-9    | 2026-04-22 | Added `## Shared Agent Skills` section (protocol-audit) | Discoverability of AyCode.Core-hosted skills from dependent repos                               | `4× non-Core primary`                                                       |
| LLMP-DEC-10   | 2026-04-23 | Created `docs-discovery` skill (parallel session)     | Paired-doc (`main` + `_ISSUES` + `_TODO`) auto-loading before code search                         | `docs-discovery/SKILL.md` + `AyCode.Core/copilot-instructions.md`           |
| LLMP-DEC-11   | 2026-04-23 | Extended `## Shared Agent Skills` with `docs-discovery` (parallel session) | Both skills now listed in each dependent repo                                | `4× non-Core primary` + `Mango.Nop.Core/copilot-instructions.md`            |
| LLMP-DEC-12   | 2026-04-24 | LOADED_DOCS prefix: full list → count+delta format    | Long lists became visual noise at scale; delta preserves self-commitment                          | `5× primary` + `docs-discovery/SKILL.md`                                    |
| LLMP-DEC-13   | 2026-04-24 | Created this Decision Log                             | Institutional memory for protocol evolution; avoid re-debating resolved choices                   | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md`                             |
| LLMP-DEC-14   | 2026-04-24 | Added `## Protocol History` section                   | Cross-repo discoverability of the Decision Log                                                    | `4× non-Core primary` + `Mango.Nop.Core/copilot-instructions.md`            |
| LLMP-DEC-15   | 2026-04-24 | Filled empty Nop.Plugin.Misc.AIPlugin instruction file | Previously 0 bytes; now minimal inherit-pattern referencing AyCode.Core + both skills + log       | `Nop.Plugin.Misc.AIPlugin/copilot-instructions.md`                          |
| LLMP-DEC-16   | 2026-04-24 | Filled empty Mango\FruitBank instruction file         | Previously 0 bytes; now minimal inherit-pattern with ⚠️ "purpose TBD" notice                      | `Mango/FruitBank/copilot-instructions.md`                                   |
| LLMP-DEC-17   | 2026-04-24 | Expanded REPOS.md: 5 repos → 8 (primary + inherit)    | Audit scope was incomplete; sub-project & plugin files were missed                                | `protocol-audit/references/REPOS.md`                                        |
| LLMP-DEC-18   | 2026-04-24 | Fixed Mango.Nop.Core `@repo` path (7 `..` → 6 `..`)   | Previous path resolved to `H:\Aycode\...` (non-existent). Corrected relative depth from repo root | `Mango.Nop.Core/copilot-instructions.md`                                    |
| LLMP-DEC-19   | 2026-04-24 | Resolved Mango.FruitBank purpose (nopCommerce host)   | Confirmed: directory is a nopCommerce deployment for FruitBank company, hosting Nop.Plugin.Misc.AIPlugin. Layer 4 (host), not TBD. Updated content accordingly. | `Mango/FruitBank/copilot-instructions.md`                                   |
| LLMP-DEC-20   | 2026-04-24 | `protocol-audit` v1.0 → v2.0: primary/inherit invariant split | SKILL.md now applies Common + Primary invariants to rows 1-5, Common + Inherit + Cross-cutting to rows 6-8. New invariants: P3 (Rule #1 count+delta format), X1 (Shared Agent Skills), X2 (Protocol History). | `protocol-audit/SKILL.md` + `protocol-audit/references/REPOS.md` (issues cleared) |
| LLMP-DEC-21   | 2026-04-24 | Docs layout: paired topics migrated to `TOPIC/README.md + TOPIC/TOPIC_*.md` pattern (Option C) | Single `docs/` folder with flat `TOPIC_*.md` files was noisy at scale; folder grouping reinforces the "folder navigation rule" and gives each topic a canonical `README.md` entry point. Option C (README.md main + topic-prefixed companions) chosen over pure Pattern B for (a) glob-pattern compatibility with old `**/TOPIC*.md`, (b) unique LOADED_DOCS basenames for companion files, (c) GitHub README auto-render preserved. Single-file topics (ARCHITECTURE, GLOSSARY, CONVENTIONS, DTOS, etc.) kept flat. | 13 `docs/` folders across 5 repos (AyCode.Core, AyCode.Blazor, Libraries, FruitBankHybridApp, Nop.Plugin.Misc.AIPlugin); ~35 file renames/moves; 13 new `README.md` index files; 4 csproj files converted from explicit file-lists to recursive glob (`docs\**\*.md`); `docs-discovery/SKILL.md` Step 2 glob patterns updated to match Pattern B layout |
| LLMP-DEC-22   | 2026-04-24 | Rule #1 LOADED_DOCS format: "basenames only" → "shortest unique short names" | After the Pattern B docs migration, many `README.md` files share the same basename across different topic folders (e.g., `LOGGING/README.md`, `BINARY/README.md`, `SIGNALR/README.md`). A bare `README.md` in the LOADED_DOCS prefix is ambiguous and breaks the self-commitment / no-re-read mechanism. New rule: basename by default (already unique for topic-prefixed companions and flat single-file topics); `TOPIC/README.md` for topic-folder READMEs; further disambiguation upward for cross-project collisions. | `5× primary` + `docs-discovery/SKILL.md` Step 4 |
| LLMP-DEC-23   | 2026-04-24 | Full cross-reference cleanup after Pattern B migration (batch sed + targeted fixes) | After the docs migration, ~45 `.md` files contained outdated paths (flat `TOPIC_*.md` refs that are now `TOPIC/TOPIC_*.md`; renamed mains `LOGGING_SERVER.md`→`LOGGING/README.md` etc.; pre-existing depth bugs like `AyCode.Core/docs/LOGGING.md` that were always wrong depth; cross-folder sibling refs inside `SIGNALR_BINARY_PROTOCOL/` pointing to `SIGNALR/` topics by basename). Three-pass cleanup: (1) batch sed on 44 files for `docs/TOPIC*.md` → Pattern B paths; (2) second sed pass for pre-existing `AyCode.Core/docs/{LOGGING,BINARY,SIGNALR}/` → `AyCode.Core/{AyCode.Core,AyCode.Services}/docs/...` depth correction (with placeholder guard to avoid double-substitution); (3) targeted Edits for cross-folder sibling refs and project-level README doc-listing tables. Final grep: zero old-style references remain. | ~45 `.md` files across all 5 repos; AyCode.Core/copilot-instructions.md rule 8 + 19; AyCode.Blazor rule 14; FruitBankHybridApp rules 15+20; 7 project-level `README.md` "doc listing" tables; 9 MGGRID sibling refs; 5 cross-folder SIGNALR↔SIGNALR_BINARY_PROTOCOL refs |
| LLMP-DEC-24   | 2026-04-24 | Phantom-reference fixes: `docs/ARCHITECTURE.md` from `.github/` + BINARY/README.md serializer-overview target | (1) `AyCode.Core/.github/copilot-instructions.md:96` had `docs/ARCHITECTURE.md#framework-vs-consumer-boundary` which resolved to `.github/docs/ARCHITECTURE.md` (non-existent) relative to the file's own location. Fixed to `../docs/ARCHITECTURE.md#framework-vs-consumer-boundary` so the path resolves to the existing repo-root `docs/ARCHITECTURE.md`. (2) `AyCode.Core/AyCode.Core/docs/BINARY/README.md:22` pointed to `docs/ARCHITECTURE.md` for "Serialization overview (Toon vs AcBinary vs AcJson)". The new `TOON/README.md` (created by a parallel session) uses the more canonical `../../Serializers/README.md` — the serializer-framework-level README that genuinely compares all three formats. Aligned BINARY/README.md to the same target for consistency. | `AyCode.Core/.github/copilot-instructions.md` + `AyCode.Core/AyCode.Core/docs/BINARY/README.md` |
| LLMP-DEC-25   | 2026-04-24 | Added "Current protocol state (quick reference)" section to the top of the Decision Log | The log grows monotonically (append-only); readers landing on it shouldn't have to scan every dated entry to learn the currently-active protocol. The new top-of-file summary captures Rules #1-5, docs layout convention, instruction-file inventory (5 primary + 3 inherit), agent skills, and Decision Log governance. Dated entries remain the source of truth for *why* each decision was made; the summary is the *what* at a glance. Archival plan noted: yearly split at ~50 entries. | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` |
| LLMP-DEC-26   | 2026-04-24 | Extended docs-sync rule with two sub-rules: `File registration` + `Issue / TODO surfacing` (initial version; superseded by 2026-04-24 revision below) | (1) **File registration** — every new `.md` must be visible in Visual Studio Solution Explorer, which requires a `<None Include=".." />` entry (or matching recursive glob) in the nearest `.csproj`. (2) **Issue / TODO surfacing** — surface concrete bugs/TODO candidates in `[DOCUMENTATION CHECK]` when not already in loaded `_ISSUES.md` / `_TODO.md`. Initial calibration: "concrete + non-duplicate + actionable — silence beats noise". **This version was revised after two external LLM critiques — see the next entry.** | `5× primary` (docs-sync rule: AyCode.Core #18, AyCode.Blazor #13, Libraries #16, FruitBank #14, FruitBankHybridApp #14) |
| LLMP-DEC-27   | 2026-04-24 | Revision of the two new sub-rules after two-session LLM review + proactive csproj glob expansion | Two external LLM critiques identified gaps in the initial sub-rule text. Applied revisions: (A) **File registration scope-limit** — check only if the new file falls OUTSIDE an existing recursive glob (zero-cost skip for the common `docs/`-path case). (B) **Issue / TODO surfacing guardrails** — added 4 explicit prerequisites (companion must be in `LOADED_DOCS` for reliable duplicate check; high confidence with quotable evidence; concrete observation; not duplicate). Added **volume cap max 3 per response**. Removed **ID assignment** from draft entries (user assigns at apply-time to avoid parallel-session collisions). Added **status-update-on-fix** clause (fixing an issue listed in loaded `_ISSUES.md` → surface `Status: FIXED` suggestion). (C) **ENFORCEMENT empty-state guard** — if nothing to report: `[DOCUMENTATION CHECK] None.` single line (no prose padding). (D) **Proactive csproj glob expansion** — added `<None Include="**\README.md" Exclude="$(DefaultItemExcludes);docs\**" />` to 9 csproj files already having `docs/**` glob; added the same pattern (without `docs/**` exclusion) to 5 csproj files lacking any md glob. Together these cover folder-level `README.md` files in code directories (Loggers, Serializers, SignalRs, DbContexts, LogItems, etc.), making them visible in VS Solution Explorer without per-file rule trigger. The rule sub-rule A now mostly fires only for truly unusual locations. Cross-reference added between sub-rule B and the existing "Identify missing documentation" clause (different targets: main docs vs companions). | `5× primary` instruction files (docs-sync rule revision); **14 csproj files** (glob expansion): 9 with `docs/**` + `**/README.md`, 5 with only `**/README.md` |
| LLMP-DEC-28   | 2026-04-24 | Created `docs-check` skill; docs-sync rule → short pointer | Observation: both Claude Code and Copilot interpret and follow *skills* more reliably than numbered rules (explicit activation, step-by-step SKILL.md, description-matching forces deliberate thought). The docs-sync rule had grown into a multi-step procedure (drift detection, missing docs, topic separation, file registration, issue/TODO surfacing with 4 prereqs + volume cap + status-update-on-fix, empty-state handling) — exactly the shape of a skill, not a rule. Created `AyCode.Core/.github/skills/docs-check/SKILL.md` (v1.0) encapsulating the full procedure in 7 steps + edge cases + negative examples. Rule #18 (and equivalents) shortened in each primary file to a single pointer: *"at the end of EVERY code-modifying response, invoke the docs-check skill ..."*. Removed ~40 lines of duplicated procedure per primary file (×5 = ~200 lines of redundant text across the workspace). Skill is read-only on loaded docs (no new `Read`/`Grep` during invocation); all patches surface as proposals (Rule #5). | **1 new skill**: `docs-check/SKILL.md`; **5 primary** copilot-instructions.md (docs-sync rule shortened); **7 non-Core** files (`## Shared Agent Skills` section extended with the `docs-check` bullet: 4 primary non-Core + 3 inherit) |
| LLMP-DEC-29   | 2026-04-24 | `protocol-audit` v2.0 → v2.1 | (a) X1 invariant extended to expect all three skills in `## Shared Agent Skills` (was two: docs-discovery + protocol-audit; now adds docs-check). (b) New **X3** invariant: the docs-sync rule in each primary file points to the `docs-check` skill (checks for backtick-wrapped `` `docs-check` `` and the skill path). (c) Applicability matrix extended: X3 applies to all 5 primary files, N/A for the 3 inherit files (they don't have the numbered docs-sync rule). | `protocol-audit/SKILL.md` |
| LLMP-DEC-30   | 2026-04-24 | Introduced globally-unique issue/TODO/decision ID system + batch-migrated existing entries | Three reasons: (a) make IDs like `ISSUE-01` unambiguous outside their containing file (DB natural-key ready, code-comment friendly, cross-repo clear); (b) remove collision risk across parallel LLM sessions (per-topic+type counter is a smaller concurrency domain than global counter); (c) standardize the inconsistent mix of existing prefixes (`PROTO-`, `DISPATCH-`, `DS-`, `CONN-`, `XCUT-`, `DESER-`, `SER-`, `SGEN-`, `BWO-`, and per-file `ISSUE-NN`/`TODO-NN`). **Format:** `{TOPIC}-{TYPE}-{N}` — topic code from registry, type = `I`(ssue) / `T`(ODO) / `B`(ug) / `C`(ritical severity override) / `DEC` (LLMP-only), N is per-topic-per-type counter starting at 1 (no zero-padding). **Topic codes:** `LOG`, `SIG`, `SBP`, `BIN`, `TOON`, `GRID` (avoids `MG`-prefix-collision with `Mg*` class naming), `XCUT`, `LLMP`. Sub-categories (`PROTO`, `DISPATCH`, `CONN`, etc.) move from ID to body header tag (`## SIG-I-1 [PROTO]: ...`). Registry maintained in `docs-check/references/TOPIC_CODES.md`. Migration: ~50 existing entries renumbered across 10 files (LOGGING, SIGNALR, SBP, BINARY, TOON topic folders) + cross-references updated workspace-wide; found and mapped the previously-uncatalogued `BWO-4` entry → `BIN-I-15`. | `docs-check/references/TOPIC_CODES.md` (new); `docs-check/SKILL.md` (Step 5 draft entry format + topic registry reference); **10 topic doc files** (IDs renumbered); cross-ref updates across ~20 `.md` files in the workspace |
| LLMP-DEC-31   | 2026-04-24 | Consolidated XCUT cross-cutting entries into dedicated `docs/XCUT/` folder | Before: cross-cutting entries (currently just `XCUT-I-1: JSON-in-Binary request parameters`) were duplicated — canonical body in `BINARY_ISSUES.md`, short cross-ref in `SIGNALR_ISSUES.md`. This pattern breaks down as more XCUT entries arrive (every added cross-cutting topic needs duplicate maintenance, and the concept of "which side is canonical" is arbitrary). **Now:** canonical home is `AyCode.Core/AyCode.Core/docs/XCUT/` (topic-folder at project level, consistent with LOGGING/, BINARY/, TOON/ placement). Contains `README.md` (explaining XCUT concept + convention), `XCUT_ISSUES.md` (canonical entries), `XCUT_TODO.md` (template + future entries). Each affected topic's file keeps a **short cross-ref** pointing to the canonical entry; body size per topic drops to ~2 lines. Migrated `XCUT-I-1` — full body now lives in `XCUT_ISSUES.md`, with cross-refs from `BINARY_ISSUES.md` and `SIGNALR_ISSUES.md`. Also updated: `BINARY_TODO.md#bin-t-1` Related-link now points to canonical; `AyCode.Core/docs/CONVENTIONS.md` JSON-in-Binary section references canonical. | New folder `AyCode.Core/AyCode.Core/docs/XCUT/` (3 files); updated `BINARY_ISSUES.md`, `SIGNALR_ISSUES.md` (XCUT sections); `BINARY_TODO.md`, `AyCode.Core/docs/CONVENTIONS.md` (related-link updates); `AyCode.Core/AyCode.Core/docs/README.md` (topic list extended) |
| LLMP-DEC-32   | 2026-04-24 | SKILL.md generalization + workspace-meta-tooling exception documented | Two related concerns raised: (1) SKILL.md files had hardcoded specific repo/project names (e.g., "5 AyCode/Mango repos (AyCode.Core, AyCode.Blazor, Libraries, FruitBank, FruitBankHybridApp)" in protocol-audit's `description`; "`AyCode.Core/AyCode.Core/docs/XCUT/`" in docs-check's Step 5). Skills should describe BEHAVIOR; specific data lives in `references/` files. (2) The `.github/skills/` registry files (`REPOS.md`, `TOPIC_CODES.md`) list higher-layer products (Layer 3 consumers like FruitBank) — a literal Framework-First Design Principle violation if interpreted strictly. **Decisions:** (a) Skills stay **universal** (one copy under `AyCode.Core/.github/skills/`, referenced by all other repos via Shared Agent Skills section) — per-layer skill duplication rejected as maintenance-hostile. (b) SKILL.md files generalized to read from `references/` registries instead of hardcoding names. (c) The `.github/` folder is **explicitly exempted** from Framework-First: it is workspace-configuration, not framework code. Rule added to AyCode.Core/copilot-instructions.md's Framework-First Design Principle section. Scope notes added to `REPOS.md` and `TOPIC_CODES.md` at their tops. **Future escape hatch:** if a skill becomes truly layer-specific (e.g., `fruit-measurement-audit` for FruitBank-only concerns), it goes in that layer's `.github/skills/`, not in AyCode.Core's. | `protocol-audit/SKILL.md` (description + invariant X3 + applicability note generalized); `docs-check/SKILL.md` (Step 5 XCUT path reference generalized); `docs-discovery/SKILL.md` (consumer-specific class-name example swapped for a placeholder); `AyCode.Core/.github/copilot-instructions.md` (Framework-First section + "Exception for workspace meta-tooling" paragraph); `protocol-audit/references/REPOS.md` (scope note header); `docs-check/references/TOPIC_CODES.md` (scope note header) |
| LLMP-DEC-33   | 2026-04-24 | `protocol-audit` v2.1 → v2.2 — added C4 invariant for Session Setup section presence | New common invariant `C4` enforces `## Session Setup` section presence across all 8 files, with references to the three skill SKILL.md files (and for inherit files, also the canonical host's `copilot-instructions.md`). Ensures the new Session Setup rule is mechanically verifiable. Applicability matrix updated: C-invariant range extended from C1-C3 to C1-C4. | `protocol-audit/SKILL.md` (version bump; new C4 invariant; applicability matrix update) |
| LLMP-DEC-34   | 2026-04-24 | Token-economics principle made explicit — amortization over multi-turn sessions is the central design principle | **Observation**: a validation session exposed an LLM reasoning bias — when asked whether the protocol's upfront cost was worth it, the agent's first answer categorized `protocol-audit/SKILL.md` (~6K tokens) as "wasteful for this specific turn" because the turn didn't invoke it. A single user reminder ("the session just started") was enough for the LLM to self-correct and reframe the cost as amortizing over the full session lifetime. **Issue**: the Session Setup rule's rationale said "one-time cost per session" but did NOT explicitly name the single-turn optimization trap. LLMs default to per-turn local optimization and can mis-judge pre-loaded content as wasteful, especially in early session turns or quick one-off queries. **Fix**: extended the `## Session Setup` "Why mandatory" paragraph in all 8 `copilot-instructions.md` files (5 primary + 3 inherit) with an explicit `**Amortization — critical, do NOT re-evaluate per-turn**` note. The note states: (a) cost is measured over the ENTIRE session; (b) the first domain question alone recoups it; (c) the alternative (repeated source-code searches per turn) costs 10-20K tokens per turn with lower quality; (d) the design depends on cross-turn amortization + Rule #3 (no-re-read) + Rule #4 (context recovery as only exception); (e) this is the **central token-economics principle** of the entire stack. Proactively inoculates future sessions against the single-turn-optimization bias that was observed. | `5× primary` + `3× inherit` `copilot-instructions.md` (Session Setup "Why mandatory" paragraph extended with Amortization sub-paragraph) |
| LLMP-DEC-35   | 2026-04-24 | Added mandatory Session Setup — pre-load 3 SKILL.md files at session start | **Problem:** Claude Code does NOT populate workspace skills into its system-reminder / native skill-registry. Previous design relied on instruction-driven invocation (rule pointer → LLM reads SKILL.md on first trigger). This is **fragile**: the agent might not recognize implicit triggers (e.g., "this is a domain question → load docs-discovery"), might forget to load the SKILL.md, or might delay loading until after a code-search has already started. A test session confirmed the risk: an LLM answered a rule-listing question without loading any skill, then retroactively loaded them only when asked directly — the first domain question would have missed the docs-discovery trigger. **Solution:** Added `## Session Setup` section to all 8 `copilot-instructions.md` files (primary and inherit). Rule mandates pre-loading of all three SKILL.md files (`docs-discovery`, `docs-check`, `protocol-audit`) at session start, immediately after reading the main `copilot-instructions.md`. For inherit files, AyCode.Core's `copilot-instructions.md` is also in the mandatory load set (because inherit files do not duplicate Rules #1-5 — the canonical host has them). Expected `[LOADED_DOCS: ...]` prefix on first response: 4 files for primary, 5 for inherit. **Cost:** ~10-13K tokens one-time per session; Rule #3 (no-re-read) prevents repeated reads. **Reliability gain:** implicit triggers fire reliably for the entire session. The `## Shared Agent Skills` section intros (in 7 non-Core files) were also updated to cross-reference the Session Setup mandate. | `5× primary` + `3× inherit` `copilot-instructions.md` (added `## Session Setup` section); `4× non-Core primary` + `3× inherit` = `7× non-Core` (Shared Agent Skills intro updated to cross-reference Session Setup) |
| LLMP-DEC-36   | 2026-04-24 | Migrated Toon docs to `TOON/README.md` + `TOON_*.md` (Option C) | Last AyCode.Core domain still on flat layout. Absorbed the orphan `ToonExtendedInfo.txt` at repo root; added paired `TOON_ISSUES.md` / `TOON_TODO.md` per convention. Verified format spec against actual code (`MetaWriter`, `DataSection`, `TypeDefinitions`, `Descriptions`), not just the legacy marketing-style txt — surfaced richer reality (placeholder system, enum backing-field detection, navigation metadata, type relation constants) absent from the old txt. Serialize-only status recorded as `TOON_TODO.md#toon-t-6`. | `AyCode.Core/docs/TOON/` (8 new files) + `AyCode.Core/docs/README.md` (topic list) + `AyCode.Core/Serializers/Toons/README.md` (stub pointer) + `ToonExtendedInfo.txt` (removed) |
| LLMP-DEC-37   | 2026-04-24 | `docs-discovery` SKILL.md hardening: literal-path tilalom + false-empty guardrail (cross-session validation feedback) | **Incident**: a parallel Copilot session executed `docs-discovery` for a logger-review query but substituted a literal `AyCode.Core/docs/LOGGING/...` path for the spec'd `**/docs/{TOKEN}/**/*.md` glob. The literal path missed AyCode.Core's project-level docs layout (`<RepoRoot>/<Project>/docs/LOGGING/`), yielded 0 matches, and Copilot concluded "docs are empty" → fell through to code-only review, skipping the loaded paired-docs set (8 known issues, 11 prioritized TODOs). **Fix scope**: minimal — 2 sentences appended to existing steps, NOT new rules. (a) Step 2 end: explicit prohibition on substituting literal `<repo>/docs/...` for the recursive `**/docs/...` glob, with one-line rationale that `**` matches both repo-root and project-level layouts in a single pass. (b) Step 3 end: false-empty guardrail — if glob returns 0 matches OR all matches are 0-byte, re-validate the glob (typo? literal substituted?) and retry once with the same token under a corrected `**/docs/...` pattern (NEVER an ad-hoc path guess) before falling through to code-search. **Rejected alternatives**: an early Copilot draft proposed 5 new numbered rules + 5 new SKILL steps (incl. a Step 0 "load every README.md" pass). Evaluation: most were redundant with existing rules (vs. hard-gate, paired-docs Step 5, Rule #1 prefix), one was based on `**`-semantics misunderstanding (proposed "two-pass" globs where the second pattern is a strict subset of the first), one was actively harmful to token economy (Step 0). Net: ~80% reduction in proposed protocol surface, same bug-class coverage. | `docs-discovery/SKILL.md` (Step 2 end + Step 3 end) |
| LLMP-DEC-38   | 2026-04-24 | Retroactively assigned `LLMP-DEC-N` IDs to existing Decision Log entries | When the globally-unique ID system was introduced (LLMP-DEC-30) with the `LLMP` topic code for LLM-protocol meta-decisions using `DEC` type, the existing ~37 Decision Log entries remained keyed by date alone. This meant the design intention (entries have unambiguous string IDs for cross-referencing) wasn't realized for historical entries. Fix: added an `ID` column as the leftmost in the 2026 table, and populated LLMP-DEC-1 through LLMP-DEC-37 in chronological order (retroactive assignment, this entry is LLMP-DEC-38 as the first ID-aware addition). Entries now referenceable by ID from code comments, other `.md` files, PR descriptions, or future DB migration. The `LLMP-DEC-N` format is append-only (IDs never renumber); superseded decisions get new entries that reference old ones by ID (e.g., "LLMP-DEC-26 superseded by LLMP-DEC-27"). | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` (ID column + 37 retroactive IDs) |
| LLMP-DEC-39   | 2026-04-24 | `docs-discovery` SKILL.md Step 2 restructuring — recursive `**/` wildcard requirement moved to prominent CRITICAL section at TOP (second iteration; LLMP-DEC-37 proved insufficient) | **Incident**: a second Copilot session exhibited the same literal-path bug that LLMP-DEC-37 was supposed to prevent — it synthesized `AyCode.Core/docs/LOGGING/README.md` (a path that doesn't exist; the real docs are at `AyCode.Core/AyCode.Core/docs/LOGGING/`, one level deeper at project-level) instead of using the recursive `**/docs/LOGGING/**/*.md` glob. LLMP-DEC-37 had appended a warning to the END of Step 2, which was not prominent enough — Copilot read Step 2, formed its own mental model of "usual docs paths", and never reached the trailing caution. **Fix**: moved the warning to the TOP of Step 2 as a `### ⚠️ CRITICAL` subsection. Content expanded: (a) explicit depth-level enumeration (repo-root `<Repo>/docs/TOPIC/`, project-level `<Repo>/<Project>/docs/TOPIC/`, nested), (b) concrete failure-mode walkthrough showing the specific "know the repo → synthesize shallow path → 0 matches → false-empty conclusion" pattern that fires for Pattern B layouts, (c) correct-vs-wrong form side-by-side examples, (d) absolute rule: NEVER drop the leading `**/` even when the repo is known. The old trailing warning was consolidated to a back-reference to the new top section to keep Step 2 from splitting the message. User rejected intermediate proposals (byte-count verification, flat `**/docs/TOPIC.md` defensive pattern) as "drótozás" (hardcoding) — fix stays structural, no glob pattern additions. | `docs-discovery/SKILL.md` (Step 2 restructuring; supersedes LLMP-DEC-37's Step-2-end placement) |
| LLMP-DEC-40   | 2026-04-24 | Rule #1 clarification: removed false "globally unique by basename" claim for `copilot-instructions.md` | **Observation**: a parallel Claude Code self-audit session noticed a literal contradiction in Rule #1. The short-name rule line 18 said `copilot-instructions.md` is "globally unique by basename" — true for a typical session (1 active repo = 1 loaded copilot-instructions.md) but FALSE for `protocol-audit` sessions, which load all 8 `copilot-instructions.md` files simultaneously. The claim conflicts with the cross-project-disambiguation rule one line above (line 17) whenever the audit use-case fires. The LLM correctly identified the ambiguity and proposed a patch. **Fix**: replaced the parenthetical "globally unique by basename" with an explicit acknowledgment of the `protocol-audit` collision case + pointer to the already-existing cross-project-disambiguation rule above. New wording uses concrete disambiguation examples (`AyCode.Core/copilot-instructions.md`, `FruitBankHybridApp/copilot-instructions.md`). The `.github/` prefix tiltás is retained — now justified as "implicit location" rather than "already unique". **Deferred (explicit YAGNI)**: proposed new `protocol-audit` C5 invariant (semantic validation: Rule #1 basename-uniqueness claims must match the actual file-set in REPOS.md). Rejected for now — one known instance isn't enough to justify invariant surface / false-positive risk; revisit if a second similar contradiction appears. | `5× primary` `copilot-instructions.md` (Rule #1 line 18 patched) |

## Known follow-ups

*(No open follow-ups. All items from previous audits resolved — see dated entries above for fix history.)*

## Notes

- Dates before 2026-04-24 are retroactive reconstructions from session history; intra-day ordering is approximate.
- For precise attribution of individual file changes, consult the git history of the affected files.
- This log is a **summary** artifact — it records the decision and its rationale, not the full diff.