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.

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.