Adam
/
AyCode.Core
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md

63 KiB
Raw Blame History

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.