caddis-plugin: Instructions file for GitHub Copilot

Validation Discipline

These rules apply whenever an agent is asked to verify, validate, audit, or check the state of files, repositories, or system components. They exist to prevent two classes of error: declaring something missing when it exists, and declaring something clean when it has pending work.

---

Rule 1 — Confirm Absence With a Text Search

Never declare a file entry missing based solely on a paginated read_file scan.

read_file with line ranges can return truncated or empty results at range boundaries without indicating the file has more content. A "(empty)" return does not mean the target content is absent.

Required protocol:

• Before writing any FAIL verdict for a missing entry, run a grep_search (or Select-String) targeting the specific term.
• An empty grep_search result is definitive proof of absence.
• A partial file read is not.

# ✅ CORRECT: confirm absence
Select-String -Path "docs\port-registry.md" -Pattern "my-service"
# Empty result = entry is absent. Non-empty = entry exists.

# ❌ WRONG: read lines 1-60, see nothing, declare absent

---

Rule 2 — Use the Primary Signal for Git Push Status

Never infer push status from git log --oneline -N decoration text or from git status.

The decorations (HEAD -> main, origin/main) in a short log are correct, but verifying by visual inspection under context load is error-prone. Dirty working tree output from git status is orthogonal to push status and must not be conflated with unpushed commits.

Required protocol:

• Use git log origin/main..HEAD --oneline explicitly.
• Empty output = zero unpushed commits. Non-empty = commits to push.
• git status and git diff answer a different question (uncommitted changes) — do not use them as push-status signals.

# ✅ CORRECT: definitive push check
git log origin/main..HEAD --oneline
# Empty = nothing to push

# ❌ WRONG: infer from git status showing modified files
# ❌ WRONG: infer from visual inspection of ref labels in git log -3