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