audit-type-ownership

Audit Type Ownership

Use this skill for non-mutating type ownership audits in the compartment repo.

Source of truth

• AGENTS.md
• docs/layers/README.md
• docs/specs/type-placement.md
• the relevant layer docs, starting with docs/layers/api.md when the user does not narrow the audit

Workflow

1. Run node .codex/skills/audit-type-ownership/scripts/audit_type_ownership.mjs from the repo root.
2. Narrow with --package <api|contracts|sdk|cli|edge|worker|docker|kube-runtime|utils|test-support> when the request is scoped. Use --format json only when a structured artifact is more useful than Markdown.
3. Read the script output before making claims. It is a heuristic inventory, not proof.
4. Treat declared workspace dependencies as package context, not automatic findings. A non-contracts import matters only when it is undeclared in the owning package or it conflicts with the relevant layer doc.
5. Treat duplicate names as move candidates only when they imply a shared serialized or cross-package owner. Package-local families such as *Input, *Context, *Plan, *Result, *Options, *State, *Config, and *App can legitimately exist in multiple packages.
6. Classify findings with this matrix:

• contracts: serialized DTOs, public *Request, *Response, *Summary, shared status/value aliases
• query layer: *Row, *Selection, *Transaction, *Executor, persistence mutation inputs
• service layer: *Input, *Context, *Plan, *Result
• app/adapter layer: *Options, *State, *Config, *App

7. Treat cross-process or cross-package payloads as contract-owned, even when the current consumer is internal.
8. Treat query/service boundary leakage and placement violations from docs/specs/type-placement.md as ownership bugs, including generic src/types/, routes/shared/, and route DTO mappers outside *.presenter.ts.
9. If the audit turns into implementation, run the narrowest relevant package checks first and then add any required special checks for the diff.

Default scope

• Start with api.
• Then sweep contracts, sdk, cli, edge, worker, docker, kube-runtime, utils, and test-support.
• Keep the audit non-mutating unless the user explicitly asks for implementation after the audit.

Output

• Policy
• Concrete findings
• Move list
• Phased refactor plan

Script

• scripts/audit_type_ownership.mjs inventories named interface and type declarations by package and file.
• It highlights duplicate type names, suspicious @compartment/* imports, query/service leaks, root export risks, package dependency context, and placement violations.
• Final ownership decisions still come from AGENTS.md, the architecture docs, and the relevant checks.