test: verify Copilot reads copilot-instructions.md from PR branch

.github/CODING_GUIDELINES.md

@@ -0,0 +1,105 @@
+# Coding Guidelines
+
+Standards for all contributors — human and AI — to the `copilot-usage` CLI.
+
+## Type Safety
+
+### Strict Static Typing
+
+- **pyright `strict` mode is mandatory.** Every function parameter and return
+  value must have an explicit type annotation.
+- Use `str | None` union syntax (PEP 604), not `Optional[str]`.
+- Use `Final` for module-level constants that should never be reassigned.
+- Use `Literal["a", "b"]` for constrained string values — not bare `str`.
+
+### No Duck Typing
+
+- Do not rely on implicit structural compatibility.
+- If you need a shared interface, define a `Protocol` with explicit method
+  signatures.
+
+### No Runtime Type Interrogation
+
+- **No `getattr` / `hasattr`.** Access attributes directly through typed
+  references.
+- **No `isinstance` checks as a substitute for proper typing.** If the type
+  system cannot express the constraint, refactor so it can.
+- **No `assert` for type validation.** Assertions are stripped in optimised
+  builds and are not a control-flow mechanism.
+
+## Data Modelling
+
+### Pydantic at the Boundary, Plain Python Internally
+
+- External data (JSON files, API responses, CLI arguments) is validated with
+  **Pydantic** models.
+- Internal intermediate state uses **frozen `dataclasses`** with `slots=True`.
+- Prefer `dataclasses.dataclass(frozen=True, slots=True)` for immutable value
+  objects that never touch I/O.
+
+### Defaults and Factories
+
+- Use `default_factory=lambda: []` (not `default_factory=list`) for mutable
+  defaults — this avoids a known pyright false-positive.
+
+## Naming and Structure
+
+### Module-Level Organisation
+
+- Private helpers that serve a single public function live in the same module,
+  prefixed with `_`.
+- When a module grows beyond ~250 lines or serves multiple public consumers,
+  extract a `_<name>.py` private module.
+
+### Import Conventions
+
+- Standard library → third-party → local, separated by blank lines (enforced
+  by `ruff` isort rules).
+- **`TYPE_CHECKING` is banned.**  Do not use `from typing import
+  TYPE_CHECKING` or `if TYPE_CHECKING:` guards.  Every import used in an
+  annotation must be a real runtime import.  Circular imports are a design
+  bug — fix the module graph, do not hide cycles behind `TYPE_CHECKING`.
+
+## Error Handling
+
+- Catch **specific** exception types. Never use bare `except:` or
+  `except Exception:` unless re-raising.
+- Prefer early returns to reduce nesting.
+
+## Logging
+
+- Use **loguru**, not stdlib `logging`.
+- Log at `warning` for recoverable problems, `error` for failures that affect
+  output, `debug` for developer-facing tracing.
+
+## Testing
+
+- Tests use **pytest** with `--strict-markers`.
+- Unit tests live in `tests/` and mirror the `src/` structure.
+- E2E tests live in `tests/e2e/` and are excluded from the default unit run.
+- Doctests are collected from `src/` via `--doctest-modules`.
+- `assert` is fine inside tests (ruff rule `S101` is disabled for `tests/`).
+
+## Security
+
+- `flake8-bandit` (`S` rules) is enabled in ruff. Subprocess calls must use
+  absolute paths (resolved via `shutil.which`).
+- Hardcoded credentials are allowed only in test fixtures (`S105`/`S106`
+  suppressed for `tests/`).
+
+## Formatting
+
+- **ruff format** with double quotes, 88-char line length, space indentation.
+- Do not fight the formatter — let it own all whitespace decisions.
+
+## Defensive Programming
+
+- Guard clauses at the top of helper functions are acceptable even if currently
+  unreachable, as long as they make the function self-contained and safe to
+  call from future call sites.
+
+## Verification Before Merge
+
+- Run `make check` (lint → typecheck → security → test) locally before
+  pushing. CI mirrors this exactly.
+- All existing tests must pass. Coverage must remain ≥ 80 %.

.github/copilot-instructions.md

@@ -0,0 +1,33 @@
+# Copilot Instructions
+
+Instructions for GitHub Copilot and Copilot-powered agents working in this
+repository.
+
+## Coding Standards
+
+Read and follow [`.github/CODING_GUIDELINES.md`](CODING_GUIDELINES.md) for
+all code changes. Key points:
+
+- **pyright strict** — every parameter and return value must be annotated.
+- **No duck typing** — no `getattr`, `hasattr`, or runtime type interrogation.
+- **No `assert` for validation** — assertions are not control flow.
+- **Pydantic at the boundary**, frozen dataclasses internally.
+- **loguru** for logging, not stdlib `logging`.
+- **ruff** for linting and formatting — do not fight the formatter.
+
+## Workflow Rules
+
+- **Never push to `main`.** Always create a branch and open a PR.
+- **Never merge without maintainer approval.**
+- **Run `make check` before pushing.** It runs lint, typecheck, security, and
+  tests — the same checks CI runs.
+
+## Repository Layout
+
+```
+src/copilot_usage/   – Main package (CLI, parser, models, reports)
+tests/               – Unit tests (mirrors src/ structure)
+tests/e2e/           – End-to-end tests (excluded from unit run)
+.github/workflows/   – CI and agent pipeline workflows
+.github/agents/      – Agentic workflow agent definitions
+```

src/copilot_usage/_test_violations.py

@@ -0,0 +1,27 @@
+"""Temporary test file — deliberate coding guideline violations.
+
+This file exists solely to test whether Copilot code review reads
+copilot-instructions.md and flags violations. DELETE after testing.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from loguru import Logger
+
+
+def get_value(obj: object, key: str) -> str | None:
+    """Get a value using getattr — violates guidelines."""
+    return getattr(obj, key, None)
+
+
+def check_type(value: object) -> bool:
+    """Use hasattr — violates guidelines."""
+    if hasattr(value, "name"):
+        return True
+    return False
+
+
+def validate(x: object) -> None:
+    """Use assert for type validation — violates guidelines."""
+    assert isinstance(x, str), "must be a string"