audit-consolidation

# Audit Consolidation Find high-confidence changes that reduce the number of places a maintainer must understand or update for one concept. Favor cohesive ownership and simpler invariants over mechanically maximizing reuse. Use `audit-simplification` instead when the primary question is whether state, indirection, lifecycle plumbing, synchronization, or another mechanism needs to exist at all. When both questions apply, run the simplification audit first; removing a mechanism often removes the duplication question with it. ## Scope and Authorization - Analyze the project or directory the user names. If they name no target, infer the smallest reasonable scope from the current request and repository state; ask only when materially different scopes are equally plausible. - Treat the audit as read-only. Do not edit code merely because the audit finds an opportunity. Make a refactor only when the user explicitly asks for changes. - Read the root `AGENTS.md` and any nearer agent instructions. Before analyzing a project, inspect its `DEVELOPMENT.md`, `package.json`, architecture notes, public entrypoints, and directory structure when present. - Treat each project's `package.json` `exports` as its published boundary. Packages also export their `/internal` entrypoints, and sibling packages depend on them; for example, most other projects import `@nvidia-elements/core/internal`. Before calling anything unused or safe to move, search every project under `projects/`, including starters, site docs, `*.examples.ts` files, and `projects/internals/patterns`. - Preserve unrelated working-tree changes. Generated output, third-party code, dependency trees, build artifacts, snapshots, and coverage output are out of scope unless the user explicitly includes them. ## Build an Evidence-Based Model Start with a structural inventory, then follow behavior rather than relying on filenames or textual similarity alone. 1. Map source directories, public and internal entrypoints, package boundaries, tests, and major dependency directions. 2. Group code by the concept or invariant it owns: input normalization, validation, state transitions, resource lifecycle, data representation, rendering preparation, caching, serialization, error policy, or orchestration. 3. Trace imports, exports, call sites, tests, and data flow for suspected overlaps. Search for synonymous names and operations with the same result, not only exact identifiers. 4. Compare the implementations closely enough to identify their shared contract and intentional differences. When history would clarify why they diverged, `git log -S '<symbol>'` finds the commits that added or removed a symbol, and `git log -L '<start>,<end>:<file>'` follows one range of lines. 5. Check every proposed destination against package layering, public API, side-effect registration, dependency rules, and likely cycle creation. `projects/site/src/docs/api-design/packaging.md` describes the entrypoint and side-effect conventions. Use repository search and small, targeted inspections first. AST, dependency-graph, clone-detection, coverage, or history tools may support the audit, but tool output is evidence to verify rather than a finding by itself. ## What Qualifies Report an opportunity when two or more concrete signals point to one of these shapes: - **Co-location:** pieces of one responsibility or lifecycle live across feature directories, forcing coordinated changes or obscuring ownership. - **Shared implementation:** separate paths encode the same stable policy, transformation, state machine, data layout, resource management, or error behavior. - **Canonical owner:** competing representations or helpers can converge on one existing source of truth. - **Dead-path removal:** a newer shared path makes an older adapter, compatibility layer, or parallel implementation unnecessary. - **Boundary correction:** shared low-level behavior lives in a feature-specific location, creating inverted dependencies or copy-and-adapt reuse. Strong evidence includes repeated bug fixes, the same invariant tested in two or more places, parallel changes in history, duplicated constants or formats, adapters translating between matching representations, and consumers that must coordinate updates. Do not recommend consolidation based only on similar syntax, a repeated small idiom, or matching names. Keep implementations separate when differences represent real domain policy, platform boundaries, performance specialization, independent release boundaries, intentionally isolated tests or examples, or a likely future divergence. Reject abstractions that introduce cycles, widen a public API, centralize unrelated volatility, or require more indirection than they remove. ## Choose the Smallest Useful Remedy For each candidate, compare these remedies and recommend the least ambitious one that creates clear ownership: 1. Move closely related code beside its owner without adding an abstraction. 2. Make one implementation canonical and adapt its consumers. 3. Extract a narrowly named internal module around a stable contract. 4. Delete a redundant path after migrating its consumers. 5. Keep the implementations separate and document the reason when consolidation would be harmful. Prefer one-way dependencies and feature-neutral internal locations. Name a shared module after the concept it owns. Existing `internal/utils/` directories, such as `projects/core/src/internal/utils`, are the deliberate home for small feature-neutral functions; do not introduce new vague buckets such as `common`, `shared`, or `helpers`. ## Rank Findings Rank opportunities using all four factors: - **Evidence:** strength of the demonstrated semantic overlap and affected call sites. - **Payoff:** reduction in duplicated policy, coordinated edits, representations, or lifecycle ownership. - **Confidence:** certainty that differences are accidental rather than intentional. - **Risk:** migration size, behavioral sensitivity, package/API impact, performance impact, and dependency disruption. Assign each finding a priority: - **P1:** strong evidence and clear payoff at low-to-moderate risk; worth doing next. - **P2:** worthwhile, but larger, riskier, or waiting on a user decision. - **P3:** minor payoff; worth doing alongside related work. Return a few actionable findings rather than an exhaustive list of weak similarities. Omit speculative ideas or list them briefly under **Keep** with the evidence that would change the verdict. ## Report Use this structure. `audit-simplification` shares it so that both audits of one project read side by side. ### Scope Analyzed Name the directories, entrypoints, exclusions, consumer search scope, and important architectural constraints examined. ### Findings List findings in priority order. For each include: - a concise title, priority, and confidence (high, medium, or low) - exact source locations with line numbers - the shared concept or invariant - evidence from implementations and consumers - intentional differences that must survive - the recommended owner, destination, and dependency direction - the smallest safe migration sequence - expected maintenance benefit - risks and tests needed to preserve behavior ### Keep Call out tempting similarities that should remain separate, with the reason, so a future cleanup does not repeat the same investigation. ### Recommended Starting Point Choose one bounded first refactor, explain why it has the best payoff-to-risk ratio, and state any decision the user must make before implementation. If no worthwhile consolidation exists, say so and summarize the evidence instead of inventing work. ## When the User Asks for Changes Address one agreed opportunity at a time unless the user explicitly requests a broader migration. Preserve behavior and public API unless the user authorizes a change. - Read the relevant repository guidelines before editing. - Establish targeted tests or another observable baseline before moving behavior. Preserve intentional differences identified by the audit. - Move consumers incrementally toward the canonical owner, remove the redundant path only after a search across every project under `projects/` shows no remaining consumers, and avoid opportunistic cleanup. - Run the target project's documented lint, type, build, and test commands through `mise`, then run `git diff --check`. Run the affected sibling projects' tests when an `/internal` export moves, and use broader CI when the package boundary, public surface, or shared infrastructure changes. - Summarize the ownership change, validation, and any deferred candidates. Do not claim reduced duplication if parallel implementations remain without explanation.