107 lines
6.9 KiB
Markdown
107 lines
6.9 KiB
Markdown
# Repo Prefixes — format spec for repo-level namespace in topic IDs
|
|
|
|
Specification of the `<PREFIX>` component in the workspace's 4-component ID format. **Each repo declares its own prefix in its own `copilot-instructions.md` `@repo` block** — there is no central prefix listing here, in line with the Framework-First Design Principle (a framework `.md` does not enumerate consumer repos).
|
|
|
|
This file lives in `AyCode.Core/.github/` because the **format spec** is workspace-meta (used by every repo). It does NOT list non-framework prefixes.
|
|
|
|
## Full ID format
|
|
|
|
```
|
|
<PREFIX>-<TOPIC>-<TYPE>-<RAND>
|
|
```
|
|
|
|
| Component | Source | Description |
|
|
|---|---|---|
|
|
| `<PREFIX>` | Each repo's own `copilot-instructions.md` `@repo` block (`prefix = "..."` field) | Repo-level namespace |
|
|
| `<TOPIC>` | `docs-check/references/TOPIC_CODES.md` | Topic code (e.g., `LOG`, `BIN`, `SIG`) |
|
|
| `<TYPE>` | `docs-check/references/TOPIC_CODES.md` | Entry type (`I` = issue, `T` = TODO, `B` = bug, `C` = critical severity override) |
|
|
| `<RAND>` | Generated at creation | 4-character random alphanumeric suffix from `[A-Z0-9]` |
|
|
|
|
**Format rules**: all uppercase, hyphen-separated, no underscores, no spaces. Hash anchors in markdown cross-refs use lowercase: `accore-log-i-k7m2`.
|
|
|
|
**Examples** (using this repo's own prefix only — see Framework-First note above):
|
|
```
|
|
ACCORE-LOG-I-K7M2 # AyCode.Core's logger issue, random suffix K7M2
|
|
ACCORE-BIN-T-W9F1 # AyCode.Core's BINARY TODO, random suffix W9F1
|
|
ACCORE-XCUT-I-X8Q1 # AyCode.Core's cross-cutting issue
|
|
LLMP-DEC-50 # workspace-meta Decision (no prefix — see "LLMP exception" below)
|
|
```
|
|
|
|
## Why per-repo prefixes
|
|
|
|
Without prefixes, IDs like `LOG-I-5` are not globally unique across repos. Two peers may independently create logger-related issues with colliding IDs. More importantly: **framework docs cannot reference consumer-side issues** per the Framework-First Design Principle (a lower-layer framework cannot depend on a higher-layer consumer). Per-repo prefixes provide:
|
|
|
|
1. **Globally unique IDs** — `ACCORE-LOG-I-K7M2` ≠ `<other-prefix>-LOG-I-K7M2`, even when topic, type, and random suffix all match.
|
|
2. **Layer enforcement is visible** — a framework doc body referencing a higher-layer-prefixed ID becomes an immediate red flag in review (the prefix mismatch reveals the dependency-direction violation).
|
|
3. **Cross-repo search via wildcard** — `*-LOG-I-*` glob/regex finds all logger issues workspace-wide, with no central registry needed; the LLM filters by prefix after retrieval.
|
|
4. **Distributed parallel work** — combined with the random `<RAND>` suffix, multiple developers can create entries in parallel branches without ID-collision at merge time.
|
|
|
|
## ACCORE — this repo's own prefix
|
|
|
|
This repo (`AyCode.Core`) uses prefix **`ACCORE`** (declared in this repo's own `copilot-instructions.md` `@repo` block, `prefix = "ACCORE"` field).
|
|
|
|
## Per-repo prefix declaration convention
|
|
|
|
Every repo participating in the workspace declares its own prefix in its `.github/copilot-instructions.md` `@repo` block:
|
|
|
|
```
|
|
@repo {
|
|
name = "<RepoName>"
|
|
prefix = "<PREFIX>" # ← prefix declared here
|
|
type = "framework" | "product" | "consumer" | ...
|
|
layer = 0..N
|
|
own-dep-repos = [...]
|
|
}
|
|
```
|
|
|
|
To discover a peer's prefix at agent runtime: read that peer's `copilot-instructions.md` (already loaded if the peer is in `own-dep-repos`). For peers NOT in `own-dep-repos` (i.e., higher-layer consumers from a framework's perspective): cross-repo wildcard search (next section) avoids needing to know the prefix in advance.
|
|
|
|
## Cross-repo ID search (no central registry needed)
|
|
|
|
When searching for entries across the workspace (e.g., "all logger issues" — across framework AND any consumer repos), agents use the prefix-wildcard glob:
|
|
|
|
```
|
|
*-LOG-I-* # all logger issues, any prefix
|
|
*-BIN-T-* # all BINARY TODOs, any prefix
|
|
*-SIG-* # all SIGNALR entries (issues + TODOs + bugs)
|
|
```
|
|
|
|
The wildcard pattern is workspace-discovery-agnostic — no central prefix list required. Result enumeration finds all matches; the LLM filters by prefix per the user's intent. The `docs-discovery` skill includes the cross-repo wildcard convention in its discovery flow.
|
|
|
|
## Random suffix spec
|
|
|
|
The `<RAND>` suffix is **4 characters from `[A-Z0-9]`** (36⁴ ≈ 1.7 million combinations per topic-type-prefix triple).
|
|
|
|
**Generation rules**:
|
|
|
|
1. Each new entry receives a fresh random suffix at creation time.
|
|
2. Before finalizing: the agent globs existing entries (active topic file + all year-bucketed archive files for that topic) and verifies the suffix is not yet used.
|
|
3. If collision detected (extremely rare — birthday-paradox 50% probability at ~1300 entries per topic-type-prefix triple): regenerate the suffix.
|
|
4. The suffix is **append-only** once assigned — never renumbered, never recycled, never reassigned to a different entry.
|
|
|
|
**At archive time** (`docs-archive` skill): performs collision-check before moving entries to year-bucketed archive files. If collision detected with an existing archive entry: skill aborts, signals the user, awaits manual resolution — no silent corruption.
|
|
|
|
## LLMP exception
|
|
|
|
`LLMP-DEC-N` Decision Log entries **do NOT receive a repo prefix**. They are workspace-meta — there is exactly one `LLM_PROTOCOL_DECISIONS.md` file (in AyCode.Core), and decisions are workspace-wide, not repo-specific. Bare format: `LLMP-DEC-1`, `LLMP-DEC-2`, ...
|
|
|
|
Sequential numbering for LLMP-DEC entries is **preserved** (legacy from before this registry existed; no random suffix). This is acceptable because the single Decision Log file enforces serialization — no parallel branches create concurrent LLMP-DEC entries that would collide.
|
|
|
|
If a future scenario emerges where workspace-meta decisions span multiple Decision Logs (unlikely), this exception will be revisited.
|
|
|
|
## Cross-references
|
|
|
|
- **Topic codes registry**: `docs-check/references/TOPIC_CODES.md` — the `<TOPIC>` component
|
|
- **Decision Log**: `LLM_PROTOCOL_DECISIONS.md` — registry of `LLMP-DEC-N` entries (workspace-meta, no prefix)
|
|
- **Per-repo prefix declarations**: each repo's own `.github/copilot-instructions.md` `@repo` block
|
|
|
|
## Picking a prefix for a new repo
|
|
|
|
When a new repo joins the workspace, it picks its own prefix (no central approval needed):
|
|
|
|
1. Choose a prefix (4-12 chars, uppercase, alphanumeric, no hyphens / underscores).
|
|
2. Verify it does NOT collide with `Ac*` / `Mg*` C# class-name prefixes (prefix must be ≥ 4 chars to avoid 2-char visual collision in mixed code/markdown content).
|
|
3. Verify it is visually distinct from prefixes of repos this new repo will reference or interoperate with (workspace-discovery-time check, not centrally enforced).
|
|
4. Declare the prefix in the new repo's `.github/copilot-instructions.md` `@repo` block (`prefix = "<PREFIX>"` field).
|
|
5. (Optional) Add an `LLMP-DEC-N` entry recording the new repo's join + prefix choice, if the new repo's existence is workspace-meta-significant.
|