# 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.
- **No skill / template version labels.** Skills and templates are continuously iterated; the Decision Log entry IS the version history. Reference changes by date or `LLMP-DEC-N` ID, not by synthetic version numbers (`v1.1`, `v2.0`, etc.) — neither in skill content, frontmatter metadata, nor in conversation when discussing changes. LLMP-DEC-45 removed legacy `metadata: version` fields from all SKILL.md files; LLMP-DEC-47 codifies the principle explicitly to prevent the linguistic regression of using `vN.M` as colloquial shorthand for "recent changes".

---

## 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) |
| LLMP-DEC-41   | 2026-04-24 | Created `adr-author` skill — 4th workspace skill, extends Session Setup pre-load from 3 to 4 | **Gap identified**: the existing skill-stack (docs-discovery, docs-check, protocol-audit) covers documentation retrieval, code↔docs drift detection, and cross-repo file-structural audit — but has no artifact-producing workflow for **pre-code architectural decisions** (greenfield repo planning, feature design, tech-stack choices, library selection, migration planning). The `{TOPIC}_TODO.md` format is an implementation queue (known scope, code ref expected, P1-P3 priority); it cannot naturally hold decision rationale, weighed alternatives, or trade-off tables. Without a dedicated artifact, design rationale tends to disappear into chat history or get flattened into TODO entries that lose the "why". **Solution**: `adr-author` skill encoding the canonical Michael Nygard ADR workflow as a structured interview (Step 1 routing → Step 2 context → Step 3 alternatives → Step 4 trade-offs → Step 5 decision → Step 6 consequences → Step 7 draft + write → Step 8 cross-refs). Tool-neutral like the other three skills. **Routing logic**: two decision-log paradigms supported — per-repo `docs/adr/NNNN-<slug>.md` Nygard-style files (product/code/domain decisions) VS workspace-level `LLMP_PROTOCOL_DECISIONS.md` table rows with ID `LLMP-DEC-N` (protocol-meta decisions). **Invocation model (new): explicit user request OR LLM-suggest-back** — LLM flags when conversation exhibits 2+ ADR-heuristics (multiple alternatives weighed, irreversible, cross-cutting, 6-18mo re-openable); user must confirm before invocation. Never auto-invoke. **Session Setup pre-load 3 → 4 skill**: consistent with existing `protocol-audit` (on-demand) pattern — the skill's content must be in context for trigger recognition. **Handoff**: `docs-check` can flag ADR-worthy observations at end-of-response; `docs-discovery` owns "how does X work" questions, `adr-author` owns "let's design X" questions. **User rationale for broader scope than greenfield-only**: user correctly pointed out ADR-worthy decisions arise in mature code too (refactors, library additions, migration paths), not just new-repo planning — the original Nygard definition supports this scope. | new: `AyCode.Core/.github/skills/adr-author/SKILL.md` + `AyCode.Core/.github/skills/adr-author/references/ADR_TEMPLATE.md`; `5× primary` `copilot-instructions.md` (Session Setup: three→four; prefix count 4→5); `3× inherit` `copilot-instructions.md` (Session Setup: three→four; prefix count 5→6); `4× non-Core primary` + `3× inherit` `copilot-instructions.md` (Shared Agent Skills intro "All three"→"All four"; new adr-author bullet added after docs-check bullet) |
| LLMP-DEC-42   | 2026-04-25 | `adr-author` SKILL.md: added "Multi-project repo case" placement guidance to Step 1 (cross-cutting vs project-scoped) | **Incident**: a Claude Code session executing `adr-author` for a bearer token design produced an excellent ADR draft but left the `docs/adr/` location ambiguous — the draft path said `docs/adr/0001-...` without resolving whether that meant `<repo>/docs/adr/` (repo root, cross-cutting placement) or `<repo>/<project>/docs/adr/` (project-scoped). The decision in question affected 2+ projects (`AyCode.Services` client + `AyCode.Services.Server`), so the placement question was real, not academic. The original SKILL.md Step 1 used `<active-repo>/docs/adr/...` placeholder which silently assumed single-project repos; multi-project layouts (which exist in this and likely other repos) had no explicit guidance. **Fix**: added a "Multi-project repo case" sub-section to Step 1 with three rules: (1) existing convention wins (Glob first; never fragment by creating a parallel folder); (2) no existing folder → match scope to placement (cross-cutting → highest common ancestor, typically repo root; project-scoped → that project's `docs/`); (3) ambiguous scope → ask the user explicitly before proceeding. Step 7's path reference updated to `<adr-folder>` resolved in Step 1, removing the misleading `<active-repo>/docs/adr/` literal. **Generic, not hardcoded**: no specific repo names or project paths in the rules — they apply to any multi-project repo. | `adr-author/SKILL.md` (Step 1 + Step 7 updates) |
| LLMP-DEC-43   | 2026-04-25 | Lazy-load shift for user-gated skills + new `docs-archive` skill + Status field convention | **Three integrated changes consolidated into one decision** because they share the underlying principle "user-gated skills are lazy-loaded; reactive skills stay pre-loaded": (A) **Lazy-load shift**: `protocol-audit` and `adr-author` (LLMP-DEC-41) move from Session Setup pre-load to lazy-load. The `## Shared Agent Skills` bullets in `copilot-instructions.md` already contain enough trigger description for the LLM to recognize when to invoke; the full SKILL.md only needs to be in context at execution time. Token savings: ~10-14K per session (3 SKILL.md × ~5K avg). (B) **New `docs-archive` skill** (lazy-loaded, user-gated + LLM-suggest-back): rotates closed entries (`Status` ∈ {Fixed, Resolved, Won't fix, Superseded by X}) from active `_ISSUES.md` / `_TODO.md` / `LLM_PROTOCOL_DECISIONS.md` into year-bucketed `*_<year>.md` archive files. Year of Status update determines destination bucket. Status-based filter (no foundational-flag complexity, no age threshold). Active file gets a 2-line pointer block at top; archive files NOT auto-loaded by `docs-discovery` (lazy-on-suspicion read pattern documented in `docs-discovery/SKILL.md` "Archive files" section). (C) **Status field convention** formalized in `TOPIC_CODES.md`: explicit value list (`Open`, `Partially Fixed`, `Fixed`, `Resolved`, `Won't fix`, `Documented limitation`, `Superseded by`), date stamping rules, partial-fix `### Resolution status` sub-section format, archive-eligibility filter. Status updates are the **one exception** to append-only — field is mutable; entry body / ID / Description remain immutable. **Cross-skill integration**: `docs-discovery/SKILL.md` gets new "Archive files" section (default-exclude year-suffixed glob; on-demand read on regression / supersession-ref / cross-ref signals). `docs-check` already had status-update-on-fix logic (LLMP-DEC-27); this entry formalizes the value vocabulary it should use. **Workflow**: `docs-archive` reports per-file analysis (Step 2), user selects scope (Step 3), generates plan with diff (Step 4), applies on explicit consent (Step 5, Rule #5). Archive operation is on-demand — no automatic monitoring, no background size checks. **Note**: an earlier in-conversation draft proposed the lazy-load shift as a standalone LLMP-DEC entry; folded into this LLMP-DEC-43 instead, since lazy-load and `docs-archive` skill share the same design rationale and benefit from being recorded as one decision. | new: `AyCode.Core/.github/skills/docs-archive/SKILL.md`; updated: `docs-check/references/TOPIC_CODES.md` (new "Status field conventions" section); `docs-discovery/SKILL.md` (new "Archive files" section); `5× primary` `copilot-instructions.md` (Session Setup: 4→2 pre-loaded SKILL.md, prefix count 5→3, lazy-load list added); `3× inherit` `copilot-instructions.md` (Session Setup: 4→2 pre-loaded SKILL.md, prefix count 6→4, lazy-load list added); `4× non-Core primary` + `3× inherit` `copilot-instructions.md` (Shared Agent Skills intro updated; new `docs-archive` bullet added after `adr-author`) |
| LLMP-DEC-44   | 2026-04-25 | Status field vocabulary simplified: 7 values → 3 (`Open`, `InProgress`, `Closed`); bulk-migrated all existing TODO/Issue entries to `Open` | **Refinement of LLMP-DEC-43 (C)**: the 7-value Status vocabulary (`Open`, `Partially Fixed`, `Fixed`, `Resolved`, `Won't fix`, `Documented limitation`, `Superseded by`) was deemed over-engineered. **Reduced to 3 values**: `Open` (active/unresolved; also used for documented-current-behaviour entries that must remain visible), `InProgress` (partial work in flight), `Closed` (done — bug fixed, decision made, TODO completed; archive-eligible). Distinctions previously encoded in the Status (Fixed vs Resolved vs Won't fix vs Superseded) move to the **entry body** — body explains "what happened" (date, ref, rationale); Status only signals "is this still in the active set?". Documented-current-behaviour entries (previously `Documented limitation`, `By design`, `Acceptable`, `Limitation`, `Upstream SDK limitation`, etc.) stay as `Open` with an optional body callout (`> **Note:** This entry documents accepted current behaviour — not scheduled for change.`). **Bulk migration** applied: every existing `Status` value in `_ISSUES.md` and `_TODO.md` files across the workspace (LOGGING, XCUT, BINARY, SIGNALR, SBP) was set to `Open` as a clean-slate starting point — future Status updates use the new 3-value vocabulary. **Archive criterion** in `docs-archive` simplified to a single rule: `Status == "Closed"` → archive-eligible. **Known anomaly**: `SIGNALR_ISSUES.md` had a single `Status: DONE` entry — also set to `Open` per the bulk-migration rule, but semantically should likely be `Closed` (work was actually done). User to manually re-mark if appropriate. **Why simpler is better**: the previous 7 values created false precision — the distinction between Fixed/Resolved/Won't fix matters in the body, not in the Status field. The `Documented limitation` value semantically conflicted with archiving (it's not "closed work"); folding it into `Open` with a body callout removes the conflict. Archive logic becomes a single equality check. | `docs-check/references/TOPIC_CODES.md` (Status section: 7 → 3 values, simpler workflow); `docs-archive/SKILL.md` (archive criterion simplified to `Status == "Closed"`); 6 files affected by bulk Status migration: `LOGGING_ISSUES.md`, `XCUT_ISSUES.md`, `BINARY_ISSUES.md`, `SIGNALR_ISSUES.md`, `SIGNALR_BINARY_PROTOCOL_ISSUES.md`, `SIGNALR_BINARY_PROTOCOL_TODO.md` (`TOON_ISSUES.md` unchanged — all real entries already `Open`) |

| LLMP-DEC-45   | 2026-04-25 | `adr-author` SKILL.md + ADR_TEMPLATE first-real-use feedback batch (9 changes); `version` field removed from all 5 SKILL.md frontmatters | First end-to-end use of `adr-author` (bearer token ADR session, `0001-user-bearer-token-flow.md`) surfaced 9 friction points across the skill and template, plus consolidates 2 previously-parked feedback items (Copilot session out-of-scope routing, Claude Code session dimensional alternatives — now subsumed). **Changes** (priority order): (#1) Step 8 #3 split into "decision-closes-entry" vs "pre-flight-closed-entry" cases — pre-flight case (entry already closed before ADR formalizes the architecture) gets a soft cross-ref to `### Related` instead of Status update; (#2) new Step 9 "Hand-off after write" — short, ask-don't-assume-next-action; (#3) Step 8 #1 explicit `<adr-folder>/README.md` Index table update (not just generic "PRODUCT_DECISIONS.md"); (#4) Step 7 NNNN re-Glob immediately before `Write` (collision safety); (#5) Step 5 opinion-when-asked nuance — frame as preference not prescription, with anti-example pair (❌ "X, egyértelmű." vs ✅ "I lean toward X because Y, but you decide."); (#6) ADR_TEMPLATE Status placeholder fixed `Proposed` → `Proposed (YYYY-MM-DD)` (was inconsistent with skill Step 5); (#7) `docs/adr/0000-TEMPLATE.md` becomes 1-paragraph pointer to canonical `references/ADR_TEMPLATE.md` — eliminates duplication / drift risk; (#8) ADR_TEMPLATE Alternatives section adds optional Reversibility/Cost/Future-flex sub-bullets with explicit "use sparingly" guidance; (#9) ADR_TEMPLATE Status comment notes Status vocabulary distinct from `_ISSUES.md` / `_TODO.md` (Open/InProgress/Closed) — see `TOPIC_CODES.md`. Plus Edge cases "Parallel LLM sessions" updated to point back to Step 7's explicit re-Glob rule (was redundant). **Housekeeping**: `metadata: version` field removed from all 5 SKILL.md frontmatters (`adr-author`, `docs-archive`, `docs-discovery`, `docs-check`, `protocol-audit`). Internal iteration doesn't need versioning ceremony — Decision Log entries are the version history. **No backward-compat concerns**: bearer token ADR (0001) was a test run, not a production consumer; no external dependents on prior skill behaviour. | `adr-author/SKILL.md` (Steps 5/7/8/9, Edge cases, frontmatter); `adr-author/references/ADR_TEMPLATE.md` (Status section, Alternatives section); `docs/adr/0000-TEMPLATE.md` (full rewrite as pointer); `docs-discovery/SKILL.md`, `docs-check/SKILL.md`, `protocol-audit/SKILL.md`, `docs-archive/SKILL.md` (frontmatter `version` field removed) |
| LLMP-DEC-46   | 2026-04-25 | `docs-discovery` SKILL.md Step 2: forward-slash mandate added (Windows backslash trap) | **Recurring failure mode**: a Copilot session in VS attempted `file_search` with a Windows-backslash glob pattern (`...\docs\**\*.md`); the glob engine silently returned 0 matches despite files existing, and the agent fell through to code-search per the same false-empty pattern that LLMP-DEC-39 addressed. Same root cause class as the `**/` lehagyás (LLMP-DEC-37, LLMP-DEC-39) — a syntactically malformed pattern returns no match, the agent interprets "no files" as "no docs exist". **Fix**: added a new `### ⚠️ Path separators — forward slashes ONLY in glob patterns` sub-section to `docs-discovery/SKILL.md` Step 2 (placed between the existing `**/` CRITICAL section and "File layout convention"). Content: forward-slash mandate regardless of host OS, correct vs wrong example, failure-mode description (silent 0 matches), absolute rule statement, cross-reference to the `**/` mandate. **Why both rules together**: the `**/` recursive mandate + the `/` separator mandate are the two most common syntactic glob errors observed in real sessions; both produce identical "0 matches → false-empty → code-search fall-through" failure mode. Documenting them adjacent in Step 2 lets the LLM see them as a paired class of pitfalls. **Bug class is host-agnostic**: glob engines uniformly require forward slashes (Microsoft.Extensions.FileSystemGlobbing, ripgrep, Node glob, Python pathlib, JS minimatch) — backslash-in-pattern is silently malformed everywhere. | `docs-discovery/SKILL.md` (Step 2 — new "Path separators" sub-section between the existing `**/` CRITICAL and "File layout convention") |
| LLMP-DEC-47   | 2026-04-25 | Decision Log governance: explicit "No skill / template version labels" clause added | **Recurring slip detected**: even after LLMP-DEC-45 removed `metadata: version` from all 5 SKILL.md frontmatters, the LLM (this agent) continued using "v1.1" colloquially in conversation as shorthand for "the recent batch of changes" — including in a substantive ADR-plan critique. The user pointed out the regression: the slip itself is evidence the principle was not explicit enough. Implicit removal of metadata fields didn't prevent the linguistic ceremony in dialogue or in cross-doc references. **Fix**: added a new bullet to the `Decision Log governance` section in this file's `## Current protocol state (quick reference)` block. The rule covers three surfaces: (a) skill content, (b) frontmatter metadata, (c) conversational / cross-doc references. Reference changes by **date or `LLMP-DEC-N` ID** instead. **Why explicit codification matters**: structural removal (deleting metadata fields) is a one-time mechanical change; linguistic habit is a recurring behavioral one. Implicit principles drift in language even when followed structurally. Codifying prevents the regression at the source — every future agent reading the governance bullets will see the rule before being tempted to introduce `vN.M` shorthand. | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` (Decision Log governance section — new bullet) |
| LLMP-DEC-48   | 2026-04-25 | `adr-author` SKILL.md Step 1 restructured: fresh-folder creation rule factored out as shared rule (covers fresh-repo + multi-project cases); template wording "copy of" → "1-paragraph pointer to" (sync with LLMP-DEC-45 #7) | **Drift detected by parallel session**: LLMP-DEC-45 #7 made `<repo>/docs/adr/0000-TEMPLATE.md` a 1-line pointer to the canonical `references/ADR_TEMPLATE.md` (eliminating duplication / drift risk). The `adr-author/SKILL.md` Step 1 fresh-repo case still said *"Propose creating `0000-TEMPLATE.md` (copy of `references/ADR_TEMPLATE.md`)"* — stale wording. Additionally, the Step 1 multi-project case did not mention 0000-TEMPLATE creation at all (implicit only via inheritance from the fresh-repo case). **Discovery context**: a parallel Claude Code session, planning a project-scoped ADR folder for `AyCode.Services/docs/adr/`, followed the SKILL Step 1 literally and proposed creating a full template copy — which would have created an inconsistent state across the workspace (one folder with pointer, another with copy). **Fix**: SKILL Step 1 restructured. The fresh-folder creation directive (`README.md` + `0000-TEMPLATE.md`) factored out of the fresh-repo case into a **shared rule applying to any newly-created `docs/adr/` folder** (whether at repo root or project-scoped). The 0000-TEMPLATE wording changed from "copy of" to "1-paragraph pointer to" the canonical, with rationale stated in-line ("single source of truth, avoids template drift"). The README.md description also extended to mention the index table. **Universality preserved (no drót)**: SKILL.md does NOT reference LLMP-DEC IDs (workspace-specific) — it states the principle directly so the skill remains portable to any workspace adopting the protocol-stack. The LLMP-DEC link lives only in this Decision Log entry. | `adr-author/SKILL.md` (Step 1 path resolution section — fresh-folder creation factored out as shared rule + canonical-pointer wording) |
| LLMP-DEC-49   | 2026-04-25 | Created `AUTH` topic — registered topic code in `TOPIC_CODES.md`, scaffolded `docs/AUTH/{README, AUTH_ISSUES, AUTH_TODO}.md` at repo root | Bearer-token ADR-0001 (`docs/adr/0001-user-bearer-token-flow.md`, `Accepted (2026-04-25)`) needs a topic home for ongoing issues, planned work, and consumer recipe. **Pre-implementation scaffold**: `README.md` is honest about pre-impl state and includes a Scope table mirroring the ADR's Decision section + a "Security: Never log secrets" guideline (auth-specific phrasing, will trim to cross-ref when `LOG-T-12` lands the canonical version in `LOGGING/README.md`); `AUTH_ISSUES.md` and `AUTH_TODO.md` are empty-state with entry-format templates. **Placement**: repo-root `docs/AUTH/` (not project-level) chosen because AUTH is cross-cutting — affects `AyCode.Services` + `AyCode.Services.Server` + `AyCode.Interfaces` + every consumer. Same parallel-to-projects positioning as `docs/adr/` and `docs/XCUT/` (sibling cross-cutting topics). **`LOG-I-9` / `LOG-I-10`** (auth security leaks closed pre-flight) remain in `LOGGING_ISSUES.md` per their existing Discovery-context note; relocation to `AUTH_ISSUES.md` as `AUTH-I-N` is a separate user-approved follow-up listed in ADR-0001's "Status migration on AUTH topic creation" section — not part of this entry. | `docs-check/references/TOPIC_CODES.md` (new `AUTH` row inserted between `LOG` and `SIG`); 3 new files: `AyCode.Core/docs/AUTH/README.md`, `AUTH_ISSUES.md`, `AUTH_TODO.md` |
| LLMP-DEC-50   | 2026-04-26 | New Rule #6 added to all primary `copilot-instructions.md` — Authority, Rule scope, Skill invocation (3 general behavioral principles) | **Diagnosis from real-world session evidence**: a parallel session reviewing FruitBank plugin docs surfaced 5 distinct misinterpretation patterns: (1) inventing topic codes ad-hoc without consulting the canonical registry; (2) proposing TOC-with-offset re-read patterns that work around the no-re-read rule's scope; (3) inventing custom URL schemes (`@Repo:`) outside markdown standard; (4) proposing empty `_ISSUES.md` files without applying the established Status convention; (5) manually reimplementing a skill's workflow instead of invoking the skill. Five distinct surfaces, **one root cause**: the session knew skills/rules existed at the surface but did not follow references to depth, did not treat authoritative registries as binding, and improvised over canonicalized procedures. **Plus self-evidence**: this assistant slipped THREE times using `vN.M` version-label colloquialism in conversation despite LLMP-DEC-47 explicitly forbidding the pattern — proof that Decision Log entries alone do NOT propagate to behavior. Decision Log governance is not session-start mandatory load; rules in `copilot-instructions.md` are. **Fix**: codify three **general** behavioral principles as Rule #6 in all 5 primary `copilot-instructions.md` files. (a) **Authority before proposal** — verify against authoritative source before inventing categories/IDs/conventions. (b) **Rule implications are part of the rule** — apply rules conservatively, don't work around scope with novel patterns. (c) **Skill invocation preferred over reimplementation** — invoke skills explicitly rather than ad-hoc reimplementation. **General, not workspace-specific**: the rule text mentions NO specific registry, skill, convention, or workspace artifact — it states principles applicable to any registry, any skill, any future workspace. **Why Rule #6, not Rule #2 extension**: Rules #1-5 are state/input/output mechanics (LOADED_DOCS prefix, docs-before-code, no-re-read, context-recovery, modification consent); Rule #6 is **behavioral correctness** of how proposals are formed — separate functional category, separate rule. **Coverage**: Authority covers misinterpretations 1, 3, 4; Rule implications covers 2; Skill invocation covers 5 — full 5/5 of observed patterns. **Why this might still not be enough**: even codified rules slip in agent behavior (the v-label evidence). Multi-LLM independent validation remains structurally necessary as the final safety net; rule-text shifts the probability, doesn't reach 100%. | `5× primary copilot-instructions.md` (new Rule #6 inserted after Rule #5, before `## Session Setup`) |

## 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.