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

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

| Date       | Decision                                              | Rationale                                                                                         | Affected                                                                    |
|------------|-------------------------------------------------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| 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`                                                                |
| 2026-04-20 | Added PER-QUESTION DOC-FIRST to Rule #2               | LLM skipped checking for relevant `.md` before jumping to code search                             | `5× primary`                                                                |
| 2026-04-21 | Expanded Rule #5 scope: "code/files" → "any file..."  | Memory / config / docs edits also need consent; old wording too narrow                            | `5× primary`                                                                |
| 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`                                                                |
| 2026-04-22 | Added "in context" definition to Rule #3              | Summary content was mistaken for actually-loaded docs (lossy compression)                         | `5× primary`                                                                |
| 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`                                     |
| 2026-04-22 | "strictly maintain rule X" → "rule 3"                 | Per-repo numbers varied (15/18/19/20/21); unified reference                                       | `5× primary`                                                                |
| 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`            |
| 2026-04-22 | Added `## Shared Agent Skills` section (protocol-audit) | Discoverability of AyCode.Core-hosted skills from dependent repos                               | `4× non-Core primary`                                                       |
| 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`           |
| 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`            |
| 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`                                    |
| 2026-04-24 | Created this Decision Log                             | Institutional memory for protocol evolution; avoid re-debating resolved choices                   | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md`                             |
| 2026-04-24 | Added `## Protocol History` section                   | Cross-repo discoverability of the Decision Log                                                    | `4× non-Core primary` + `Mango.Nop.Core/copilot-instructions.md`            |
| 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`                          |
| 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`                                   |
| 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`                                        |
| 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`                                    |
| 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`                                   |
| 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) |

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