---
name: protocol-audit
description: Audit `.github/copilot-instructions.md` files for protocol consistency across the invocation-point repo and its dependency tree (discovered at runtime via `own-dep-repos` walking). Two file types are recognized by content — **primary** (full numbered AI AGENT CORE PROTOCOL) and **inherit** (reference-only: blockquote pointer to the canonical protocol, no duplicated numbered rules). The skill applies the appropriate invariant set per type. Use when the user asks to "audit protocol", "check instruction consistency", "verify repo rules", "check cross-repo drift", or after modifying the AI AGENT CORE PROTOCOL in any repo. Produces a per-file × invariant table with concrete patch suggestions; does NOT modify any file without explicit consent.
compatibility: Designed for Claude Code and GitHub Copilot (VS). Requires read access to the invocation-point repo + all its transitive `own-dep-repos`.
metadata:
  author: Fullepi
---

# Protocol Audit

Verify that all `.github/copilot-instructions.md` files registered in `references/REPOS.md` share a consistent AI AGENT CORE PROTOCOL ecosystem. **Primary** files contain the full numbered protocol; **inherit** files reference the canonical protocol without duplicating the numbered rules.

## Before you start

This skill READS files and REPORTS findings. It MUST NOT modify any file. Patch suggestions are surfaced as diffs for the user to review and approve. Follow Rule #5 (or equivalent) from the active repo's `copilot-instructions.md`.

## Step 1 — Discover the audit set (runtime walk)

Determine the **invocation-point repo** from the active workspace context (the repo containing the user's currently-active session).

Walk the dependency tree:
1. Read the invocation-point repo's `.github/copilot-instructions.md` `@repo` block.
2. For each `own-dep-repos` entry, resolve the path relative to the repo root and read that dep's `@repo` block.
3. Continue transitively until no new deps are found.
4. Audit set = {invocation-point repo} ∪ {all walked deps}.

Classify each file by content inspection (no central registry of files):
- **Primary** — contains the `🛑 AI AGENT CORE PROTOCOL (CRITICAL ENFORCEMENT)` header → full invariant set.
- **Inherit** — contains `follows the AI Agent Core Protocol defined in <HOST>` blockquote AND lacks the primary header → reduced invariant set.
- **Unknown** — matches neither → record as `UNKNOWN`, flag for manual review.

Read `references/REPOS.md` for **framework-side metadata only**: canonical protocol host designation, the framework's own file table (typically a single row — AyCode.Core), and any known issues. Per the Framework-First Design Principle, that file lists only ACCORE; consumer participation in the audit is auto-discovered through the walk above. The skill does not hardcode any repo / project names.

Effective audit scope per invocation:
- From `AyCode.Core` (Layer 0) → audits only `AyCode.Core`.
- From a higher-layer repo → audits invocation-point + full transitive dep tree below it.

## Step 2 — Read each instruction file

For each entry in both tables, read `<abs-path>\.github\copilot-instructions.md` once. Record the full text keyed by the logical name and **file type** (primary / inherit). If a file is empty (0 bytes), record as `EMPTY` and still run the size-sensitive invariants (expected: all fail).

Do NOT re-read a file that is already in your LOADED_DOCS list (per Rule #3 of the active repo's protocol).

## Step 3 — Run invariant checks by file type

Each invariant yields `PASS` / `FAIL` / `N/A` (not-applicable-to-this-type) and, on FAIL, an evidence snippet.

### 3A — Common invariants (applied to ALL 8 files)

**C1. `@repo` block has all 5 required fields**
Inside the `@repo { ... }` block, the keys `name`, `prefix`, `type`, `layer`, `own-dep-repos` must all be present.

**C2. `own-dep-repos` paths resolve to existing directories**
For each `"<dep-name>: <relative-path>"` entry, resolve `<repo-root>/<relative-path>` and check the directory exists.

**C3. `@repo.prefix` has valid format**
The `prefix` value must be uppercase, 4-12 chars, alphanumeric only (no hyphens / underscores / spaces / lowercase). It must NOT collide with `Ac*` / `Mg*` C# class-name prefixes (must be ≥ 4 chars, see `REPO_PREFIXES.md`).

**C4. `## Session Setup` section present with reactive + user-gated skill classification**
Header `## Session Setup` must appear. The section body must reference:
- 2 **reactive** skills (mandatory pre-load at session start): `docs-discovery/SKILL.md`, `docs-check/SKILL.md`.
- 3 **user-gated** skills (lazy-loaded on demand, listed for trigger-recognition): `protocol-audit/SKILL.md`, `adr-author/SKILL.md`, `docs-archive/SKILL.md`.

For inherit files, the section must additionally reference loading the canonical `copilot-instructions.md` (from the host repo — e.g., AyCode.Core).

Expected first-response `[LOADED_DOCS]` counts: **3 for primary** (this `copilot-instructions.md` + 2 reactive `SKILL.md`), **4 for inherit** (this file + canonical `copilot-instructions.md` + 2 reactive `SKILL.md`). Lazy-loaded skills add to the count only when first invoked. Updated per LLMP-DEC-43 (5-skill 2-reactive/3-user-gated matrix) and LLMP-DEC-64 (text-drift fix from initial 3-skill wording).

### 3B — Primary-only invariants (applied to files classified as **primary** in REPOS.md)

**P1. Rule numbering is contiguous 1..N**
Extract all `^\d+\. \*\*` lines. Numbers must form `1, 2, 3, ..., N` with no gaps and no duplicates.

**P2. Rule count is ≥ 5**
The AI AGENT CORE PROTOCOL has five core rules. Sections after Rule #5 (Conventions etc.) may add more; the first 5 are mandatory.

**P3. Rule #1 uses count+delta format**
Substring `N files (+K this turn` present in Rule #1. Old substring `comma-separated list of .md files currently in your context` must be ABSENT.

**P4. Rule #2 contains `CROSS-REPO HARD-GATE`**

**P5. Rule #2 contains `PER-QUESTION DOC-FIRST`**

**P6. Rule #3 is the NO-RE-READ rule**
Header matches `STRICT NO-RE-READ POLICY (ANTI-LOOP)`.

**P7. Rule #3 contains the "in context" definition**
Substring `lossy compressions` present.

**P8. Rule #4 contains auto-detection triggers**
Substring `Auto-detection triggers` present AND substring `LOADED_DOCS: NONE` present.

**P9. Rule #5 scope is broad**
Substring `any file (code, documentation, configuration, memory, or otherwise)` present.
Negative: substring `delete code/files without` must be ABSENT (old wording).

**P10. `strictly maintain rule 3` reference exists**
Substring `strictly maintain rule 3` present. Old references (`rule 15`, `rule 18`, `rule 19`, `rule 20`, `rule 21`) must be absent.

### 3C — Inherit-only invariants (applied to files classified as **inherit** in REPOS.md)

**I1. References the canonical protocol host**
Substring `follows the AI Agent Core Protocol defined in <HOST>` present, where `<HOST>` is the repo designated as the canonical host in REPOS.md (the file content's literal phrasing must match the host's name — this workspace's files currently say "AyCode.Core"). If REPOS.md designates a different host, both the inherit files and this invariant's expected substring are updated in lockstep.

**I2. Does NOT duplicate numbered Rules #1-5**
Must NOT contain the header `🛑 AI AGENT CORE PROTOCOL (CRITICAL ENFORCEMENT)` (that belongs to primary files only). If the file has `^\d+\. \*\*MANDATORY OUTPUT PREFIX` or similar, flag as FAIL — the inherit file has leaked primary content.

**I3. Has a link to the Decision Log**
Substring `LLM_PROTOCOL_DECISIONS.md` present (via the Protocol History section — see X2 below).

### 3D — Cross-cutting invariants (applied to all files EXCEPT the canonical protocol host)

The **canonical protocol host** is the repo designated in `references/REPOS.md` as housing the shared skills, Decision Log, and registries (typically the first row labeled the "host" in REPOS.md). That host does not need to reference itself. These X invariants apply to every other file registered in REPOS.md.

**X1. `## Shared Agent Skills` section present with all five skills**
Header `## Shared Agent Skills` must appear. All five bullets must be listed: `docs-discovery` (reactive), `docs-check` (reactive), `protocol-audit` (user-gated), `adr-author` (user-gated), `docs-archive` (user-gated). Updated per LLMP-DEC-43 + LLMP-DEC-64.

**X2. `## Protocol History` section present**
Header `## Protocol History` must appear AND it must reference the Decision Log at the canonical host's location (e.g., `<HOST_REPO>/.github/LLM_PROTOCOL_DECISIONS.md`; the concrete path is resolvable from REPOS.md).

**X3. Docs-sync rule points to `docs-check` skill** *(primary files only)*
In each primary file's docs-sync rule (the numbered rule whose title begins "Keep all .md documentation in sync"), the substring `` `docs-check` `` (backtick-wrapped skill name) must be present, AND a reference to the docs-check skill's `SKILL.md` path (e.g., `.github/skills/docs-check/SKILL.md` or a correct relative variant) must be present.

### Invariant applicability matrix

| Invariant set | Canonical host | Other primary | Inherit |
|---------------|----------------|---------------|---------|
| Common (C1-C4) | ✓ | ✓ | ✓ |
| Primary-only (P1-P10) | ✓ | ✓ | N/A (skip) |
| Inherit-only (I1-I3) | N/A (skip) | N/A (skip) | ✓ |
| Cross-cutting (X1-X2) | N/A (skip — the host does not cross-reference itself) | ✓ | ✓ |
| Cross-cutting (X3) | ✓ | ✓ | N/A (skip — inherit files don't have the numbered docs-sync rule) |

The primary/inherit classification and the "canonical host" designation both come from `references/REPOS.md`. This skill does not hardcode any specific repo or project name.

Use `N/A` in the report cell, not `PASS`, for skipped invariants — so it's obvious the check wasn't applicable.

## Step 4 — Produce the report

Emit a markdown report with three sections:

### 4A — Summary table

One row per file, grouped by type. Columns: the invariant IDs from Step 3 (C1, C2, C3, P1..P10, I1..I3, X1, X2). Cell values: `PASS` / `FAIL` / `N/A` / `MISSING` / `UNREADABLE` / `EMPTY`.

Use short column headers (C1, P1, P2, I1, X1, etc.) — 19 columns is dense but fits in a readable table when values are 2-4 chars.

### 4B — Failure details

For every FAIL, list:
- File name + type (primary / inherit)
- Invariant ID (e.g., P3, I1, X2)
- Evidence — the offending line, missing substring, or unresolved path
- Suggested patch — a concrete `old_string` / `new_string` pair (or "create this section" scaffold) the user can review

### 4C — Known-issues reconciliation

Cross-reference any FAIL with the "Known issues" section in REPOS.md. If a failure is already tracked as a known issue, mark it `FAIL (known)` so the user can distinguish fresh regressions from pre-existing TODOs.

## Step 5 — DO NOT apply patches

End the report with:

> All checks complete. N failures detected (M known, N-M new). To apply any of the suggested patches, reply with "apply patches P3, I1" (or similar IDs). No files have been modified.

Wait for **explicit** user consent before using any edit / write tool. Per Rule #5: phrases like "we are just thinking" / "what do you think" do NOT constitute approval.

## Tool usage

This skill is tool-neutral. Map these capabilities to the host agent's tools (per the active repo's `CLAUDE.md`):

- Reading files: `Read` (Claude Code), `get_file` (Copilot), or equivalent
- Globbing / directory existence: `Glob`, `file_search`, `ls`, `Test-Path`
- Applying patches (only after consent): `Edit`, `replace_string_in_file`

## Edge cases

- **Repo path missing from disk:** Skip that file, record `MISSING` in every invariant cell, continue with the others.
- **File read fails:** Record `UNREADABLE`, continue.
- **File is 0 bytes:** Record `EMPTY`; every content-sensitive invariant returns FAIL. Still run C1-C3 (they'll fail too, which is correct signal).
- **Multiple `@repo` blocks in one file:** Audit the first one; flag the duplicate as its own finding.
- **Rule order differs** (e.g., Rules #3 and #4 swapped in a primary file): invariants P6 and P8 fail independently — do not try to auto-reorder.
- **Unfinished mid-edit:** If a file has obviously truncated content (cut off mid-sentence), record `CORRUPT` and stop that file's audit.
- **Ambiguous file type** (has both `AI AGENT CORE PROTOCOL` header AND the inherit-blockquote substring from I1): flag as FAIL on I2 and P1 — file has structural identity crisis, user must resolve.
- **New file not in REPOS.md:** Do NOT audit it automatically. Report it separately as `"Unregistered .github/copilot-instructions.md found at <path> — add to REPOS.md to include in future audits."`
