# Fret Boundary Checks

> This skill should be used when the user asks to "run layering checks", "verify crate boundaries", "prevent winit/wgpu leakage", or "refactor across crates safely". Provides a guardrail workflow (layering checks, forbidden-dep spot checks, drift reports) to keep contract crates portable during refactors.

- Skill: `latias94/fret-boundary-checks` (Agent Skill)
- Install (CLI): `npx skillmds@latest add latias94/fret-boundary-checks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/latias94/fret-boundary-checks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: latias94 (https://skillmd.com/u/latias94)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/latias94/fret-boundary-checks

---


# Fret boundary checks (guardrails)

This skill is for **quick guardrails** that keep bottom-up refactors safe and portable.

## When to use

- Before/after refactors that move code across crates.
- When you suspect an accidental dependency edge (e.g. backend deps leaking into contract crates).
- When a file/module is drifting into a “god file” and you want an early warning.

## Inputs to collect (ask the user)

Ask these before running guardrails so you know what “green” means:

- What refactor is happening (move code across crates, split modules, new dependency)?
- Which crates are in scope (especially kernel/contract crates like `fret-core`, `fret-ui`)?
- What is the risk: backend dep leakage, reverse deps, feature allowlists, module bloat?
- What is the expected outcome: just “detect”, or “fix + land with gates”?
- Does the refactor also change a public/facade surface that first-party examples or docs teach?

Defaults if unclear:

- Run layering + module-size drift before and after the change, and keep allowlists as a last resort.
- If exports/facades move, also run a first-party surface drift check (docs/UI Gallery/source-policy tests), not just dependency checks.

## Smallest starting point (one command)

- `python3 tools/check_layering.py`

## Quick start

Run the always-on guardrails:

- Layering (workspace crate boundaries):
  - `python3 tools/check_layering.py`
- Module size drift (keep god files visible):
  - `python3 tools/report_largest_files.py --top 30 --min-lines 800`
- If public authoring surfaces moved:
  - `cargo nextest run -p fret-ui-gallery --lib gallery_curated_shadcn_surfaces_stay_explicit`

## Workflow

### Core guardrails (always-run)

- Layering (workspace crate boundaries):
  - `python3 tools/check_layering.py`
- Module size drift (keep god files visible):
  - `python3 tools/report_largest_files.py --top 30 --min-lines 800`

### Crate-focused checks (when auditing one crate)

- Quick audit snapshot:
  - `python3 tools/audit_crate.py --crate <crate>`
- Public-surface drift spot check:
  - `docs/crate-usage-guide.md`
  - `docs/shadcn-declarative-progress.md`
  - `apps/fret-ui-gallery/src/lib.rs`

### Interpreting failures (common cases)

- `check_layering.py` failures mean a **workspace->workspace** dependency edge violates ADR policy.
  - Fix by moving code to the correct layer, or by adding an explicit allowlist entry only when
    the crate is intentionally “wiring heavy”.
- Huge-file drift means you should split by responsibility before expanding behavior surface.
- Passing layering does **not** mean the public story is still coherent.
  - If a facade/export moved, check whether docs and UI Gallery exemplars now teach a stale import or stale seam.

## Definition of done (what to leave behind)

- Minimum deliverables (3-pack): Repro (guardrail commands), Gate (layering), Evidence (anchors). See `fret-skills-playbook`.
- `python3 tools/check_layering.py` is green (or any allowlist change is justified and minimal).
- Module-size drift is understood and addressed (split responsibilities before “god files” grow).
- If a violation was fixed, the fix is placed in the correct layer (prefer moving code over adding allowlists).
- If the refactor touches behavior, at least one regression artifact exists (unit test or diag script).
- If the refactor changes a public authoring surface, docs and first-party exemplars are updated alongside the boundary fix.

## Notes

- These scripts are intentionally “best-effort” and fast; they do not replace deeper audits.
- If a guardrail needs to become normative (CI gate), document it in the workstream and add a
  stable “Fast vs Full” command set.

## Evidence anchors

- Layering checks: `tools/check_layering.py`, `docs/dependency-policy.md`
- Crate audit snapshot: `tools/audit_crate.py`
- Module-size drift: `tools/report_largest_files.py`
- Crate/layer usage map: `docs/crate-usage-guide.md`
- Shadcn authoring golden path: `docs/shadcn-declarative-progress.md`
- UI Gallery authoring gates: `apps/fret-ui-gallery/src/lib.rs`
- UI Gallery exemplar surface: `apps/fret-ui-gallery/src/ui/snippets/`

## Examples

- Example: refactor across crates without breaking layering
  - User says: "Move this helper into fret-core—will it violate boundaries?"
  - Actions: run layering checks, scan forbidden deps, and keep portability constraints explicit.
  - Result: a refactor plan that does not leak platform deps into contract crates.

## Common pitfalls

- Treating allowlists as a first-choice fix (prefer moving code to the correct layer).
- Ignoring a “small” layering violation during a refactor (it compounds quickly).
- Measuring file-size drift after the refactor lands (run guardrails early).
- Declaring a refactor “safe” because layering is green while first-party docs/examples still teach stale imports or stale seams.

## Troubleshooting

- Symptom: layering check fails unexpectedly.
  - Fix: inspect the failing edge, then decide whether to move code (preferred) or split a new crate (only if necessary).
- Symptom: a platform crate dependency sneaks into a contract crate.
  - Fix: introduce an abstraction boundary (traits/data structs) and keep platform wiring in `*-platform-*`/runner crates.

## Related skills

- `fret-crate-audits` (deeper crate-by-crate review)
- `fret-fixture-driven-harnesses` (when large test matrices become unreviewable)