framework-import-boundary-auditor

name	framework-import-boundary-auditor
description	Audit and fix import-boundary violations with deterministic facade-first rewrites and explicit exceptions. Use when requests mention deep imports, boundary cleanup, or core-facade migration.

Skill: framework-import-boundary-auditor

Trigger Signals

Use this skill when requests include:

• "import boundary"
• "deep import"
• "move import to core"
• "scan for boundary violations"
• "facade-first"

Do Not Use When

• Request is only UI copy/style changes.
• Request is only runtime behavior debugging with no import churn.

Required Inputs

• Scope: file list, folder, package, or full repo.
• Rules:
  • docs/ai/framework/rules/import-boundaries.md
  • docs/ai/framework/CODING_STANDARDS.md
• Current architecture references in:
  • docs/ai/framework/API_SURFACES.md
  • docs/ai/framework/packages/core.md

Preflight

1. Capture current dirty state: git status --short
2. Scan imports in scope using rg.
3. Build a short mapping of allowed facade exports vs package exports.

Deterministic Procedure

1. Find violations:

• deep package internal paths (@asyra/*/src/*)
• relative cross-package imports
• app-level direct imports where core facade already exists

2. Classify each finding:

• must_fix_to_core_facade
• allowed_direct_package_import
• blocked_missing_facade_export

3. Apply minimal edits:

• rewrite imports only
• avoid behavior changes unless required by typing

4. If blocked by missing core export:

• add curated export in @asyra/core
• avoid wildcard/bulk re-export patterns

5. Re-run targeted checks for touched packages/apps:

• lint/type/build commands for affected scope

Validation Matrix

• Boundary scan: no @asyra/*/src/* in target scope.
• Build/type checks: pass for impacted package(s).
• Runtime behavior: unchanged unless explicitly requested.

Required Output Format

Return results with these sections:

1. Findings

• list each violation category and count

2. Changes

• list import rewrites and any new facade exports

3. Validation

• commands run + pass/fail

4. Open Items

• allowed exceptions or blocked items

Guardrails

• Do not introduce new deep imports while fixing others.
• Do not move app domain logic into core.
• Local commits may close completed, validated steps/stages; never push unless the user explicitly requests the remote operation. Follow docs/ai/workflows/git-commit-push-policy.md.

Failure Policy

If facade ownership is ambiguous:

• do not guess
• keep current behavior
• output two concrete options with tradeoffs