diff --git a/.github/LLM_PROTOCOL_DECISIONS.md b/.github/LLM_PROTOCOL_DECISIONS.md index 04ef336..534bf82 100644 --- a/.github/LLM_PROTOCOL_DECISIONS.md +++ b/.github/LLM_PROTOCOL_DECISIONS.md @@ -32,12 +32,12 @@ Active as of **2026-04-26**. For the full evolution history, see the dated table - **2 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). - Each non-Core file has `## Shared Agent Skills` + `## Protocol History` sections. - **Per-repo `prefix` field** (LLMP-DEC-58): every `@repo` block declares its own ID-prefix (`prefix = "ACCORE"`, `"ACBLAZOR"`, `"MGNOPLIB"`, `"MGNOPCORE"`, `"MGFBANKPLUG"`, `"FBANKNOP"`, `"FBANKAPP"` — 7 prefixes, 1 per repo). -- **`.github/` files follow Framework-First** (LLMP-DEC-58 narrows the previous workspace-meta-tooling exception): each repo declares its own info (prefix, topics, etc.); only `LLM_PROTOCOL_DECISIONS.md` (workspace-meta history) and transient migration artifacts (`MIGRATION_ID_MAPPING.md`) may cross layers. Cross-layer awareness in tooling uses runtime discovery via `own-dep-repos` walking, not centralized listings. +- **`.github/` AND `docs/` files follow Framework-First** (LLMP-DEC-58 narrowed `.github/` exception; LLMP-DEC-62 extended the rule to `docs/`): each repo declares its own info (prefix, topics, etc.); only `LLM_PROTOCOL_DECISIONS.md` (workspace-meta history) and transient migration artifacts (`MIGRATION_ID_MAPPING.md`) may cross layers. Cross-layer awareness in tooling uses runtime discovery via `own-dep-repos` walking, not centralized listings. **Single bounded exception** per repo: `CONSUMERS.md` (one file per repo, optional) MAY list higher-layer repos that consume this one — bounded consumer-awareness for change-impact assessment, NOT framework-on-consumer coupling. AyCode.Core's lives at `AyCode.Core/CONSUMERS.md`. **Issue / TODO / Decision ID format** (globally unique, 4-component as of LLMP-DEC-50..59): - Format: `---` (e.g., `ACCORE-LOG-I-K7M2`, `ACCORE-SIG-T-D7Q4`, `ACCORE-BIN-B-XXXX`, `ACCORE-XCUT-I-X8Q1`, `ACBLAZOR-GRID-T-V4P7`, `LLMP-DEC-50`). - **``** (repo namespace): declared per-repo in `copilot-instructions.md` `@repo` block (`prefix = "..."` field, LLMP-DEC-58). Format spec + the framework's own `ACCORE` listing: `AyCode.Core/.github/REPO_PREFIXES.md`. Higher-layer prefixes are declared in their own repos (Framework-First — no central enumeration). -- **``** (framework / ACCORE topics): `LOG` (logger), `AUTH` (authentication), `SIG` (SignalR), `SBP` (SignalR binary protocol), `BIN` (binary serializer), `TOON` (Toon serializer), `XCUT` (cross-cutting within ACCORE), `LLMP` (LLM-protocol meta — bare format, no prefix). Higher-layer topics live in each repo's own `/.github/TOPIC_CODES.md` (e.g., AyCode.Blazor's `GRID`); see `AyCode.Core/.github/skills/docs-check/references/TOPIC_CODES.md` for the per-repo extension convention. +- **``** (framework / ACCORE topics): `LOG` (logger), `AUTH` (authentication), `SIG` (SignalR), `SBP` (SignalR binary protocol), `BIN` (binary serializer), `TOON` (Toon serializer), `XCUT` (cross-cutting within ACCORE), `META` (meta-tooling issues/TODOs about the protocol stack itself, LLMP-DEC-62), `LLMP` (LLM-protocol meta — bare format, no prefix). Higher-layer topics live in each repo's own `/.github/TOPIC_CODES.md` (e.g., AyCode.Blazor's `GRID`); see `AyCode.Core/.github/skills/docs-check/references/TOPIC_CODES.md` for the per-repo extension convention. - **``** (universal): `I` = issue, `T` = TODO, `B` = bug, `C` = critical (severity override), `DEC` = decision (LLMP-only). - **``** (random suffix): 4-char `[A-Z0-9]`; ~1.7M combinations per `--` triplet. Generated at entry creation; uniqueness verified via glob over active + archive files; collision triggers regeneration. **Avoids parallel-branch ID-collisions at merge time.** - **LLMP exception**: `LLMP-DEC-N` entries (workspace-meta Decision Log) skip the prefix and use sequential `N` — single-file serialization avoids parallel-branch concern. Bare format `LLMP-DEC-1`, `LLMP-DEC-2`, ... @@ -176,6 +176,7 @@ The "primary" vs "inherit" distinction is defined in `protocol-audit/references/ | LLMP-DEC-59 | 2026-04-26 | Phase 6 of ID-format migration: cross-file cross-ref cleanup completed (37 edits across 13 files); migration end state — 0 OLD-format IDs in non-exception files workspace-wide | Phase 6 of LLMP-DEC-50 migration — final cross-file cross-ref cleanup. Inter-topic body anchors and uppercase ID body refs updated per the Phase 4 mapping (LLMP-DEC-56). **Files updated** (13): topic-pair files for inter-topic anchors (`XCUT_ISSUES.md`, `LOGGING_ISSUES.md`, `LOGGING_TODO.md`, `BINARY_TODO.md`, `SIGNALR_ISSUES.md`, `SIGNALR_TODO.md`, `SIGNALR_BINARY_PROTOCOL_TODO.md`); top-level cross-ref doc `CONVENTIONS.md` (4 anchor refs); AUTH topic body refs (`docs/AUTH/README.md` + `AUTH_ISSUES.md` — LOG-I-9 / LOG-I-10 renamed); ADR cross-refs (`docs/adr/0001-user-bearer-token-flow.md` — body + anchor refs renamed; `AyCode.Services/docs/adr/0001-acbinary-decorator-feature-stack-design.md` — SBP-T-5..8 renamed); `XCUT/README.md` outdated 'How XCUT-*-N IDs are numbered' section rewritten to reflect random-suffix format. **Pending forward-refs decision** (deferred from Phase 4): `LOG-T-12` and `SBP-T-9` chose **option (b)** per the LLMP-DEC-50 migration plan — rewrite references to 'forthcoming TODO' / 'no ID assigned yet' instead of reserving placeholder IDs; ID gets assigned when the entry is actually filed in `..._TODO.md`. **Pre-existing typo fixed**: `LOGGING_TODO.md` L88 had stale anchor `SIGNALR_TODO.md#log-t-5` (path → SIGNALR_TODO.md but anchor was `log-t-5`; intent was clearly `sig-t-5`) — corrected to `SIGNALR_TODO.md#accore-sig-t-m5l6`. **Code-comment refs (`.cs` files across all 7 repos)**: 0 OLD-format IDs found via cross-repo grep — no code edits required. **Migration end state**: 0 OLD-format IDs in any non-exception file workspace-wide; 3 allowed-exception files contain remaining OLD-format references — `MIGRATION_ID_MAPPING.md` (transient lookup table, see LLMP-DEC-58 retention policy), this `LLM_PROTOCOL_DECISIONS.md` (workspace-meta history), and `REPO_PREFIXES.md` (single pedagogical 'LOG-I-5' example illustrating the OLD format collision problem — kept intentionally to motivate the prefix design). **Migration scope summary** (Phases 1-6, LLMP-DEC-53/54/55/56/57/58/59): ~270 edits across ~25-30 files; 79 IDs renamed to 4-component random-suffix format; 5 of 7 repos clean of OLD format (the 2 with the legacy mapping/history files are the documented exceptions); all sister docs and ADRs updated; `.cs` code comments clean. | 13 files: 7 topic-pair / sister docs (inter-topic body anchors); 1 top-level (`CONVENTIONS.md`); 2 AUTH docs; 2 ADRs; 1 XCUT/README format-spec rewrite; **37 edits in Phase 6**; **~270 edits across all migration phases (1-6)** | | LLMP-DEC-60 | 2026-04-26 | `## Current protocol state (quick reference)` summary section refreshed to reflect LLMP-DEC-50..59 outcomes (ID-format migration + Framework-First retightening + 7-instruction-file workspace) | After Phases 1-6 of the ID-format migration, the top-of-file summary section (introduced by LLMP-DEC-25 as a "what's currently active" snapshot, separate from the append-only dated entry table) had become stale on multiple counts: (a) "Active as of 2026-04-24" pre-dated all the migration entries; (b) ID format section described the OLD 3-component `--` format pre-LLMP-DEC-50; (c) instruction file count "8 total: 5 primary + 3 inherit" pre-dated LLMP-DEC-51 (`Mango.FruitBank` deletion → 7 total: 5 primary + 2 inherit); (d) skill list mentioned only 3 skills (was outdated since LLMP-DEC-43 introduced the 5-skill 2-reactive/3-user-gated matrix), used `vN.M` version labels (banned by LLMP-DEC-47), and described `protocol-audit` as reading the central `references/REPOS.md` (Phase 5.1 / LLMP-DEC-58 redesigned it for runtime discovery via `own-dep-repos` walking + content-based file-type classification); (e) Scope codes table referenced `3× inherit` and `all 8`. **Updates applied**: date → 2026-04-26; ID format → 4-component `---` with `` per-repo declaration + `` random-suffix spec + LLMP exception + cross-repo prefix-wildcard search note + cross-links to REPO_PREFIXES.md and per-repo TOPIC_CODES.md; instruction file count → 7 total (5 primary + 2 inherit) with brief notes on LLMP-DEC-51/52 (Mango.FruitBank deletion + FBANKNOP re-attribution) and LLMP-DEC-58 (per-repo `prefix` field added to all 7 `@repo` blocks); agent skills → 5 skills (2 reactive pre-loaded + 3 user-gated lazy-loaded) per LLMP-DEC-43, version labels removed; `protocol-audit` description updated for Phase 5.1 runtime-discovery design + new C1/C3 invariants; scope codes table → `2× inherit` + `all 7`; new note: `.github/` files follow Framework-First (LLMP-DEC-58 narrows the previous workspace-meta-tooling exception). **Append-only governance preserved**: dated entry table (LLMP-DEC-1..60) untouched; the summary section is by design a mutable snapshot per LLMP-DEC-25 (*"the dated entries remain the source of truth for *why* each decision was made; the summary is the *what* at a glance"*). | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` (`## Current protocol state` section — date L9; "Instruction files" L30-33 + 2 new bullets on `prefix` field and Framework-First; ID format L35-40; agent skills L42-45; "Scope codes" table L99-100) | | LLMP-DEC-61 | 2026-04-26 | Phase 7 (closure) of ID-format migration: migration formally complete | Phase 7 of LLMP-DEC-50 migration — **formal closure stamp**. All 7 phases of the original LLMP-DEC-50 plan executed: Phase 1 (LLMP-DEC-53) `REPO_PREFIXES.md` registry creation; Phase 2 (LLMP-DEC-54) `TOPIC_CODES.md` 4-component update; Phase 3 (LLMP-DEC-55) skill `SKILL.md` text updates with placeholders + cross-repo glob; Phase 4 (LLMP-DEC-56) `MIGRATION_ID_MAPPING.md` survey + 79-ID random-suffix generation; Phase 5 (LLMP-DEC-57) per-topic rename across 7 topics (132 edits); Phase 5.1 (LLMP-DEC-58) Framework-First retightening of `.github/` registries + per-repo `prefix` field added to all 7 `@repo` blocks + MIGRATION_ID_MAPPING retention policy revision; Phase 6 (LLMP-DEC-59) cross-file cross-ref cleanup (37 edits, 13 files); summary refresh (LLMP-DEC-60). **Final verification confirmed in LLMP-DEC-59 + cross-checked here**: 0 OLD-format IDs in any non-exception `.md` file or `.cs` file workspace-wide; the 3 allowed-exception files (`MIGRATION_ID_MAPPING.md` transient, `LLM_PROTOCOL_DECISIONS.md` workspace-meta history, `REPO_PREFIXES.md` single pedagogical 'LOG-I-5' example) intentionally retain OLD-format references for documented reasons. **Migration totals across LLMP-DEC-53..61**: ~270 edits, ~25-30 files modified, 79 IDs renamed to 4-component random-suffix format, 7 `@repo` blocks gained `prefix` field, 12+ registry/skill files restructured for Framework-First, 1 new file (`AyCode.Blazor/.github/TOPIC_CODES.md`). **Outstanding scheduled event** (NOT new work — auto-triggered): 2026-05-10 LLM-targeted deletion-review for `MIGRATION_ID_MAPPING.md` per LLMP-DEC-58 retention policy. Any LLM reading the file from that date onward must surface a deletion-confirmation prompt to the user; the prompt text is embedded in the file's header. **Migration formally complete** as of this entry; further protocol-stack work proceeds on the 4-component foundation. | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` (this entry only — closure stamp; no file edits outside the Decision Log) | +| LLMP-DEC-62 | 2026-04-26 | Three protocol-stack additions: (a) `META` topic for meta-tooling issues/TODOs; (b) docs-side Framework-First rule with bounded `CONSUMERS.md` exception; (c) `adr-author` skill complexity-aware ask-back trigger restructure | **User-driven coherent batch** addressing 3 long-tail observations from the Phase 1-6 migration: **(1) Mental tracking failure** for protocol-stack issues. The 5-skill stack + 7 repos + per-repo registries had grown complex enough that issues observed mid-session (e.g., `LOGGING_TODO.md` L88 path/anchor typo, `Current protocol state` summary staleness, `docs-check` runtime-discovery deferral, anchor-mismatch typo class) had no formal home — they either landed in LLMP-DEC entries (which are meant for closed decisions, not open issues) or got lost. **Fix**: new `META` topic registered in `TOPIC_CODES.md` (ACCORE-META-*); `META_ISSUES.md` + `META_TODO.md` created at `AyCode.Core/.github/`; seeded with 3 META-T entries from the migration's deferred items: `ACCORE-META-T-J9N4` (docs-check runtime discovery for per-repo TOPIC_CODES.md), `ACCORE-META-T-K2P7` (protocol-audit anchor-mismatch detection invariant), `ACCORE-META-T-F8R3` (Current protocol state summary auto-staleness detection). Empty-state ISSUES file with template. **(2) Docs-side Framework-First** was implicit but not codified. Phase 5.1 (LLMP-DEC-58) retightened `.github/`, but `docs/` files still allowed cross-layer references in principle. User clarified the rule extends to `docs/` AND added a **bounded consumer-awareness exception**: a single `CONSUMERS.md` per repo MAY list higher-layer consumers for change-impact assessment when working in that repo. **Fix**: new sub-bullet in `AyCode.Core/.github/copilot-instructions.md` `## Framework-First Design Principle` section after the Phase-5.1 workspace-meta-history exception paragraph; new file `AyCode.Core/CONSUMERS.md` listing the 6 known ACCORE consumers (ACBLAZOR, MGNOPLIB, MGNOPCORE, MGFBANKPLUG, FBANKNOP, FBANKAPP) with brief usage notes + change-impact lens. The `CONSUMERS.md` is the SINGLE place in ACCORE allowed to name consumer repos; other docs / code stay consumer-agnostic. Top-of-tree consumer products (FBANKNOP, FBANKAPP) need no own CONSUMERS.md. **(3) `adr-author` skill over-trigger / under-trigger.** The previous "When to invoke" section had a flat list of trigger phrases ("let's plan X", "design Y", "döntsük el Y vagy Z") that fired too liberally for trivial planning AND missed architectural intent without the explicit "ADR" keyword. User proposed a 3-tier model: explicit ADR-keyword → auto-trigger; implicit planning + complexity-sniff → ASK-BACK; trivial → no trigger. **Fix**: `adr-author/SKILL.md` `## When to invoke` section restructured into 4 sub-cases — "Explicit ADR invocation (auto-trigger)" / "Implicit planning request (ASK BACK)" / "Trivial — no ADR" / "Proactive flag (drift)". Complexity-sniff heuristics enumerated explicitly (cross-cutting, cross-repo, reversibility-low, ≥2 alternatives, vocabulary signals, re-openable, new-API). Ask-back template is bilingual (Hungarian + English). Default behaviour: ASK if complexity-sniff fires; never silently auto-invoke. **Coherence**: the 3 changes reinforce each other — META topic gives meta-tooling issues a durable home; CONSUMERS.md formalizes a Phase 5.1 implicit gap with a Framework-First-respecting design; adr-author refinement reduces over-classification of "design discussion" as ADR-worthy (which would otherwise pollute the META topic with mis-classified entries). **Self-evidence**: this very batch was tested against the new adr-author trigger logic — user said *"de most nem kell ehhez adr"* (= "no ADR needed for this") and asked for the 3 changes done in one go; the new SKILL.md flow correctly handles this as "Implicit planning + ASK BACK + user said 'no'" → no `adr-author` skill invocation, just structured execution. | new files: `AyCode.Core/.github/META_ISSUES.md`, `AyCode.Core/.github/META_TODO.md` (3 seeded TODOs), `AyCode.Core/CONSUMERS.md`; modified: `AyCode.Core/.github/skills/docs-check/references/TOPIC_CODES.md` (META row added between XCUT and LLMP), `AyCode.Core/.github/copilot-instructions.md` (Framework-First section sub-bullet for docs-side rule + CONSUMERS.md exception), `AyCode.Core/.github/skills/adr-author/SKILL.md` (`## When to invoke` section restructured into 4 sub-cases) | ## Known follow-ups diff --git a/.github/META_ISSUES.md b/.github/META_ISSUES.md new file mode 100644 index 0000000..a743213 --- /dev/null +++ b/.github/META_ISSUES.md @@ -0,0 +1,48 @@ +# META — Known Issues (workspace meta-tooling) + +For planned/actionable work see `META_TODO.md`. + +Active issues for the workspace meta-tooling itself: protocol stack, skills, registry conventions, `.github/` files. Distinct from code-domain topics (LOG, BIN, SIG, etc.) which track code/feature concerns. + +## In scope + +- Skill correctness or coverage gaps (`docs-discovery`, `docs-check`, `protocol-audit`, `adr-author`, `docs-archive`) +- Registry / convention drift (`REPO_PREFIXES.md`, `TOPIC_CODES.md`, `protocol-audit/references/REPOS.md`) +- Protocol-stack inconsistencies (Rule #1-6 wording, `@repo` block format, ID-format edge cases) +- `.github/` infrastructure issues (folder structure, file naming conventions, generation rules) +- ADR / Decision Log governance issues (e.g., `Current protocol state` summary staleness) + +## Out of scope + +- Code-domain issues (those go to `LOG_ISSUES.md`, `BIN_ISSUES.md`, etc.) +- One-off historical events — those go to `LLM_PROTOCOL_DECISIONS.md` as decisions +- Forward-looking work that has been formally decided — that's a TODO (`META_TODO.md`) not an issue + +## Active entries + +*(No `ACCORE-META-I-*` entries yet — file just created (LLMP-DEC-62). Add the first entry below as concrete issues are observed.)* + +## Issue entry template + +``` +## ACCORE-META-I-XXXX: Short title + +**Severity:** Trivial / Low / Minor / Major / Critical · **Status:** Open / InProgress / Closed (YYYY-MM-DD) · **Area:** + +### Description +What's broken or inconsistent in the meta-tooling, with quotable evidence (file path + line number, or skill behaviour). + +### Root cause +Why it's like that. + +### Fix direction +Proposed approach. + +### Resolution +(Filled when Status moves to `Closed` — what / where / why per `TOPIC_CODES.md` Status conventions.) + +### Related +- Sibling: `META_TODO.md#accore-meta-t-xxxx` (if applicable) +- Cross-topic: `_ISSUES.md#accore-...` (if domain-spillover) +- LLMP-DEC: `LLMP-DEC-N` (if a decision documents the resolution) +``` diff --git a/.github/META_TODO.md b/.github/META_TODO.md new file mode 100644 index 0000000..9dbeb75 --- /dev/null +++ b/.github/META_TODO.md @@ -0,0 +1,140 @@ +# META — TODO (workspace meta-tooling) + +For known issues see `META_ISSUES.md`. + +Planned work for the workspace meta-tooling itself: protocol stack, skills, registry conventions, `.github/` files. Distinct from code-domain topics. + +## Priority legend + +- **P0** blocker · **P1** important · **P2** nice-to-have · **P3** idea + +--- + +## ACCORE-META-T-J9N4: `docs-check` skill — runtime discovery for per-repo `TOPIC_CODES.md` + +**Priority:** P2 · **Type:** Skill enhancement · **Status:** Open · **Area:** `docs-check/SKILL.md` topic-code validation +**Origin:** Phase 5.1 / LLMP-DEC-58 deferral + +### Description + +After Phase 5.1, `TOPIC_CODES.md` became framework-only (ACCORE topics only — see `AyCode.Core/.github/skills/docs-check/references/TOPIC_CODES.md`). The `docs-check` skill still validates topic codes only against that single file (framework-only nézőpont). + +When `docs-check` is invoked from a higher-layer repo with its own `/.github/TOPIC_CODES.md` (e.g., `AyCode.Blazor/.github/TOPIC_CODES.md` declaring `GRID`), the skill currently does NOT find or honour it. Consumer-side topic codes are unrecognized — the skill either falsely flags valid consumer topics as "unknown topic" or skips the validation entirely. + +### Fix direction + +Update `docs-check/SKILL.md` Step 5 (Topic code selection) and the topic-loading logic to: +1. Read framework's `TOPIC_CODES.md` (current behaviour). +2. Walk the **active repo's** `@repo.own-dep-repos` recursively. +3. For each walked repo, check if `/.github/TOPIC_CODES.md` exists; if so, union its topic codes into the active set. +4. Validate against the merged set. + +Mirror the runtime-discovery pattern adopted by `protocol-audit` in Phase 5.1 (`protocol-audit/SKILL.md` Step 1). + +### Acceptance criteria + +- `docs-check` running from `AyCode.Blazor` recognizes both ACCORE topics (LOG, BIN, ...) AND ACBLAZOR topics (`GRID`). +- `docs-check` running from `AyCode.Core` only sees ACCORE topics (Framework-First — no awareness of higher layers). +- No central enumeration of consumer topic registries needed. + +### Related + +- LLMP-DEC-58 (Phase 5.1 deferral noted) +- `protocol-audit/SKILL.md` Step 1 (parallel runtime-discovery design) + +--- + +## ACCORE-META-T-K2P7: `protocol-audit` skill — auto-detect path/anchor mismatches in markdown cross-refs + +**Priority:** P3 · **Type:** Skill enhancement (new invariant) · **Status:** Open · **Area:** `protocol-audit/SKILL.md` +**Origin:** Phase 6 (LLMP-DEC-59) — `LOGGING_TODO.md` L88 typo discovered mid-migration + +### Description + +A real class of typo: a markdown link's path-part references one file, but the anchor-part refers to an ID belonging to a different file. Example observed pre-Phase-6: `LOGGING_TODO.md` line 88 had `../../../AyCode.Services/docs/SIGNALR/SIGNALR_TODO.md#log-t-5` — path → SIGNALR_TODO.md, but anchor `#log-t-5` is a LOG-T anchor (intent was clearly `#sig-t-5`). The intent-vs-reality mismatch was silent: markdown renderers don't validate cross-file anchor existence; the broken link "looks fine" until clicked. + +### Fix direction + +Add a new audit invariant (e.g., `D1` — docs-link integrity, applies to `docs/` files): +1. Parse all `[text](#)` patterns and bare `.md#` references in loaded `.md` files. +2. For each: resolve `` to a target file; extract heading-derived anchors from the target; verify `` exists. +3. FAIL with evidence (file + line) and suggested fix (closest-match anchor in target file). + +Skill stays read-only; reports findings; user approves any patch (Rule #5). + +### Acceptance criteria + +- Catches the `LOGGING_TODO.md` L88 class (different-file mismatched anchor). +- Catches stale anchors after a renamed heading (anchor exists in old form, target now uses new ID). +- Low false-positive rate (auto-generated heading anchors resolve correctly per GitHub-flavored markdown rules). + +### Related + +- LLMP-DEC-59 (typo fix during Phase 6 — discovery context) + +--- + +## ACCORE-META-T-F8R3: `Current protocol state` summary auto-staleness detection + +**Priority:** P3 · **Type:** Skill enhancement · **Status:** Open · **Area:** `protocol-audit/SKILL.md` (or `docs-check/SKILL.md`) +**Origin:** Phase 6 + LLMP-DEC-60 summary refresh + +### Description + +The `Current protocol state (quick reference)` section at the top of `LLM_PROTOCOL_DECISIONS.md` is a mutable snapshot per LLMP-DEC-25 design. After multiple LLMP-DEC entries land, the snapshot drifts from reality. + +Drift instances observed during the Phase 1-6 migration (all caught only at Phase 6 closure during a manual review): +- `Active as of 2026-04-24` while LLMP-DEC entries up to 2026-04-26 had been added. +- `8 instruction files` while LLMP-DEC-51 reduced count to 7. +- OLD 3-component ID format described while LLMP-DEC-50..59 migrated to 4-component. +- Skill version labels (`v2.2`, `v1.0`) violating LLMP-DEC-47. +- `protocol-audit` description still mentioned `references/REPOS.md` central read after LLMP-DEC-58 redesigned to runtime discovery. + +Manual refresh worked (LLMP-DEC-60), but a periodic/automated reminder would catch drift earlier. + +### Fix direction + +Two complementary options (pick one or combine): + +**(a) `protocol-audit` invariant `M1`** (meta-summary integrity, optional): +- Parse `Current protocol state` section claims (date, file count, skill list, ID format). +- Compare against ground truth (filesystem walk, file content). +- Surface drift with suggested patch. + +**(b) `docs-check` skill** flags the summary section as stale if N (e.g., N ≥ 3) new LLMP-DEC entries have been added since the summary's last refresh date. + +### Acceptance criteria + +- The drift cases above (date, file count, skill list, ID format, version labels) all detectable. +- User can mark a known-deferred summary update as `Status: InProgress` to suppress the warning. +- Low-friction: warning only, never blocking. + +### Related + +- LLMP-DEC-25 (summary section design) +- LLMP-DEC-60 (most recent manual refresh) +- LLMP-DEC-62 (this META-TODO's introduction) + +--- + +## TODO entry template + +``` +## ACCORE-META-T-XXXX: Short title + +**Priority:** P0 / P1 / P2 / P3 · **Type:** Skill enhancement / Convention update / Registry change / Docs / Cleanup · **Status:** Open / InProgress / Closed (YYYY-MM-DD) · **Area:** +**Origin:** + +### Description +What needs to be done and why, with quotable evidence (file paths, behaviour observation, etc.). + +### Fix direction +Proposed approach. + +### Acceptance criteria +- Concrete observable outcomes. + +### Related +- Sibling: `META_ISSUES.md#accore-meta-i-xxxx` (if a known issue spawned this TODO) +- LLMP-DEC: `LLMP-DEC-N` (if a decision motivated this work) +``` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8ac6fbe..e6c4d89 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -132,6 +132,8 @@ Framework design = **"write the base first, derive the specific later"**. Plan f The Framework-First rule applies to C# code, namespaces, types, domain `.md` docs (under `docs/`), AND `.github/` tooling — except the narrow workspace-meta history above. If AyCode.Core is ever extracted as a standalone framework, the framework code AND its `.github/` tooling stay layer-clean. +**Docs-side Framework-First — bounded consumer-awareness exception (LLMP-DEC-62):** the same Layer N → Layer ≤ N reference principle applies to ALL `.md` files (not just `.github/`). Cross-layer awareness in tooling uses runtime discovery via `own-dep-repos` walking, not centralized listings. **Single bounded exception per repo**: a repo with consumers above it MAY have ONE `CONSUMERS.md` (or similar — single file per repo) listing which higher-layer repos consume it — bounded consumer-awareness for change-impact assessment, NOT framework-on-consumer coupling. Other docs/code MUST stay consumer-agnostic. Top-of-tree consumer products (no higher layer above) need no `CONSUMERS.md`. AyCode.Core's lives at `AyCode.Core/CONSUMERS.md` and is the SINGLE place in this repo allowed to name consumer repos. + Full doctrine: `../docs/ARCHITECTURE.md#framework-vs-consumer-boundary` ## Key Abstractions diff --git a/.github/skills/adr-author/SKILL.md b/.github/skills/adr-author/SKILL.md index b4d49c1..6993a18 100644 --- a/.github/skills/adr-author/SKILL.md +++ b/.github/skills/adr-author/SKILL.md @@ -12,29 +12,62 @@ Structured interview-style skill that captures architecturally significant decis ## When to invoke -### Explicit user triggers -- "tervezzük meg X", "let's plan X", "design the W module" +### Explicit ADR invocation (auto-trigger — no ask-back) + +User message contains the literal keyword **"ADR"** or **"Architecture Decision Record"** (case-insensitive, any language): +- "create an ADR for X", "write a decision record about Y" +- "csináljunk egy ADR-t Z-re", "ez ADR-érdemes" +- "this is ADR-worthy" + +→ **Invoke directly**, proceed to Step 1. Skip the complexity sniff. The user has explicitly named the formal mode. + +### Implicit planning request (ASK BACK first if complex) + +User uses planning/design language **WITHOUT** the "ADR" keyword: +- "tervezzük meg X", "let's plan X" +- "design the W module" - "döntsük el Y vagy Z", "decide between Y and Z" -- "válasszunk ", "choose an approach to V" -- "milyen megközelítést", "what's our approach to W" -- "create an ADR for …", "write a decision record about …" +- "válasszunk approach-ot V-re", "choose an approach to V" +- "milyen megközelítés", "what's our approach to W" -### LLM-suggest-back (you flag, user confirms) +→ Apply the **complexity sniff** below. If ANY one heuristic fires, **ask back** — do not auto-invoke. If none fires, the request is treated as conversational planning (structured response, but no ADR file). -When the current conversation exhibits **two or more** of these heuristics, flag the user: +**Complexity sniff** (any single one is enough to trigger the ask): +- **Cross-cutting** — touches ≥ 2 topics (LOG + SIG, BIN + TOON, etc.) +- **Cross-repo** — touches ≥ 2 repos (especially framework↔consumer boundary) +- **Reversibility low** — DB schema change, public API shape, breaking change, deployment-affecting +- **≥ 2 valid alternative approaches** mentioned or implied +- **Vocabulary signals**: "design", "approach", "strategy", "decide between", "choose", "alternatives" (vs. "tweak", "rename", "fix") +- **Re-openable question** — something someone might reasonably re-open in 6-18 months asking "wait, why did we pick this?" +- **New public-facing API** shape being shaped -- Multiple alternatives being actively weighed -- Decision that is irreversible or expensive to reverse -- Cross-cutting impact (touches 2+ modules, or framework↔consumer boundary) -- A question someone might reasonably re-open in 6-18 months and ask "wait, why did we pick this?" -- Non-trivial dependency or library choice -- New public-facing API shape being discussed +**Ask-back template** (LLM emits this; waits for user response BEFORE invoking): -Example flag phrasing: +> "Ez ADR-érdemesnek tűnik mert {concrete heuristic 1, heuristic 2 — name them}. Akarsz formális ADR-t (`adr-author` skill: kontextus → alternatívák → trade-offs → döntés → következmények, durable `.md` artifact-tal) — vagy elég egy gyors strukturált terv (válasz formájában, fájl nélkül)?" -> "Ez egy architektúra-szintű választásnak tűnik (több alternatíva, irreverzibilis lehet). Érdemes lenne ADR-formába önteni — invokáljam az `adr-author` skill-t? (Jelezd, ha inkább folytassuk simán válaszként.)" +**User response paths**: +- "yes" / "formal ADR" / "igen ADR" / "csináljuk" / "mehet az ADR" → proceed to Step 1 +- "no" / "quick plan" / "gyors terv" / "csak egy terv" → DO NOT invoke this skill; respond conversationally with a structured plan (bullet points, alternatives if any, recommendation — but no `.md` artifact created) +- Ambiguous → ask follow-up question, do NOT auto-invoke. Default = ASK rather than guess. -**User confirmation is required** before proceeding to Step 1. Never auto-invoke. +### Trivial — no ADR, no ask-back + +Obviously small request the LLM can confidently classify: +- Method rename, variable rename +- Single-file typo fix +- Isolated bug fix (already-understood problem) +- Doc tweak (formatting, link update, single-paragraph rewrite) +- Code-comment improvement + +→ Just do the work. No ADR ask-back. No invocation. + +### Proactive flag (drift into architectural territory) + +When the conversation drifts into architecturally significant territory **WITHOUT** the user's explicit planning request — e.g., a "how does X work" thread that surfaces 2 alternative implementations the user is now mentally weighing — the LLM may proactively flag: + +> "Ez a beszélgetés architektúra-szintű választáshoz vezet ({observation — what specific signals you saw}). Érdemes lenne ADR-formába önteni — invokáljam az `adr-author` skill-t? (Jelezd, ha inkább folytassuk simán válaszként.)" + +Same complexity sniff as the implicit-planning case. **User confirmation always required** — never auto-invoke from a drift signal. ### When NOT to invoke - Trivial decisions: variable names, local refactors, formatting diff --git a/.github/skills/docs-check/references/TOPIC_CODES.md b/.github/skills/docs-check/references/TOPIC_CODES.md index b17abeb..ff436e4 100644 --- a/.github/skills/docs-check/references/TOPIC_CODES.md +++ b/.github/skills/docs-check/references/TOPIC_CODES.md @@ -19,6 +19,7 @@ To make IDs like `ACCORE-LOG-I-K7M2`, `ACCORE-SIG-B-3R9P`, `ACCORE-XCUT-I-A4B7` | `BIN` | BINARY | AcBinary serializer: features, format, writers, source generator | `AyCode.Core/AyCode.Core/docs/BINARY/` | | `TOON` | TOON | Toon serializer: LLM-optimized format with @meta/@types/@data sections | `AyCode.Core/AyCode.Core/docs/TOON/` | | `XCUT` | cross-cutting | Issues / TODOs spanning ≥2 ACCORE topics — one canonical home, referenced from each affected topic | `AyCode.Core/AyCode.Core/docs/XCUT/` | +| `META` | meta-tooling | Issues/TODOs **about the workspace meta-tooling itself**: skills, registries, `.github/` conventions, ADR/Decision Log governance, protocol-stack edge cases. Distinct from code-domain topics (LOG, BIN, etc.). | `AyCode.Core/.github/META_ISSUES.md` + `AyCode.Core/.github/META_TODO.md` | | `LLMP` | LLM-protocol meta | LLM protocol decisions (Decision Log entries only — uses `LLMP-DEC-N` form, no prefix) | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` | ## Type codes (universal across all repos) diff --git a/CONSUMERS.md b/CONSUMERS.md new file mode 100644 index 0000000..7f126da --- /dev/null +++ b/CONSUMERS.md @@ -0,0 +1,41 @@ +# AyCode.Core — Consumer Workspace Map + +> **Bounded consumer-awareness exception** to the Framework-First Design Principle (`.github/copilot-instructions.md` → `## Framework-First Design Principle` → "Docs-side Framework-First", LLMP-DEC-62). This single file lists which higher-layer repos consume `AyCode.Core` (Layer 0 framework). For change-impact assessment when modifying ACCORE — NOT a coupling vector. +> +> **Strict rule**: AyCode.Core code, types, namespaces, topic IDs, and any other `.md` files (`docs/`, `.github/` excluding the narrow workspace-meta-history exception) MUST NOT name any specific consumer listed here. **This is the SINGLE place** in ACCORE that may name consumer repos. + +## Workspace consumer map (as of 2026-04-26) + +| Prefix | Repo | Layer | Type | Path (workspace-relative) | Brief usage | +|----------------|-------------------------------|------:|---------------------|--------------------------------------------------------------------|------------------------------------------------------------------------------| +| `ACBLAZOR` | AyCode.Blazor | 1 | framework (UI) | `Aycode/Source/AyCode.Blazor` | Extends ACCORE base classes for Blazor / MAUI UI | +| `MGNOPLIB` | Mango.Nop Libraries | 1 | framework (libs) | `Mango/Source/NopCommerce.Common/4.70/Libraries` | Domain framework for NopCommerce-plugin development | +| `MGNOPCORE` | Mango.Nop.Core | 2 | framework (sub) | `.../Libraries/Mango.Nop.Core` | Inherit-protocol; sub-framework on top of MGNOPLIB | +| `MGFBANKPLUG` | Nop.Plugin.Misc.AIPlugin | 3 | consumer (plugin) | `.../Plugins/Nop.Plugin.Misc.AIPlugin` | FruitBank nopCommerce plugin source | +| `FBANKNOP` | FruitBank | 2 | product (server) | `Mango/Source/FruitBank` | nopCommerce server source for the FruitBank deployment | +| `FBANKAPP` | FruitBankHybridApp | 2 | product (hybrid) | `Mango/Source/FruitBankHybridApp` | MAUI/Blazor hybrid client app | + +(See `.github/REPO_PREFIXES.md` for the prefix scheme; each consumer's own `.github/copilot-instructions.md` `@repo` block declares its `prefix` value per LLMP-DEC-58.) + +## When modifying AyCode.Core — change-impact lens + +Use this list to assess change impact: +- A breaking change to a base class affects all 6 consumers above (cascading rebuilds + verification). +- A new feature gated behind opt-in DI extension → no cascade, just new capability. +- A signature change in a widely-used interface (e.g., `IAcSignalRClientBase`) → at minimum: ACBLAZOR + MGNOPLIB + MGFBANKPLUG + FBANKNOP + FBANKAPP all need verification. +- A change to ID format / topic-code conventions → MGNOPCORE and MGFBANKPLUG (inherit-protocol) plus all primary repos need updating. + +**Do NOT** use this list to write framework code that conditionalizes on specific consumers. Generic abstractions only. The list is a **HEURISTIC for impact**, not an **INPUT to logic**. + +## Maintenance + +When a repo joins or leaves the workspace consuming AyCode.Core, update the table above. The list ITSELF is workspace-meta-tooling — not framework code domain. + +**Future automation candidate** (filed as `ACCORE-META-T-?` in `.github/META_TODO.md`): `protocol-audit` skill could compute this list dynamically from each repo's `@repo.own-dep-repos` (inverse-graph traversal) and verify against this file — eliminating manual upkeep. + +## Cross-references + +- **Decision Log entries**: LLMP-DEC-62 (this file's introduction + docs-side Framework-First rule); LLMP-DEC-58 (Phase 5.1 `.github/` retightening — precedent); LLMP-DEC-25 (workspace-meta exception family). +- **Repo prefix registry (framework's own)**: `.github/REPO_PREFIXES.md`. +- **Topic registry (framework's own)**: `.github/skills/docs-check/references/TOPIC_CODES.md`. +- **META TODOs / Issues**: `.github/META_TODO.md` / `.github/META_ISSUES.md`.