codebaseiq 0.1.0

package/docs/architecture-coherence-vision.md

@@ -0,0 +1,254 @@
+# Architecture Coherence Vision
+
+## Purpose
+
+codebaseiq should help a maintainer answer two different questions:
+
+1. What architecture does this codebase actually have?
+2. Where does the implementation contradict the architecture the project intends to preserve?
+
+The dependency graph can answer neither question alone. It records which files rely on which other files. Architectural judgment connects those facts to the real responsibilities, public contracts, runtime boundaries, and maintenance work that gave the code its structure.
+
+The product vision is therefore a combination of:
+
+- an `architecture` query that measures declared boundaries and dependency rules;
+- a directory-architecture skill that helps an agent discover, name, test, and gradually enforce those rules;
+- drift and health integrations that expose architectural changes without pretending every unusual import is a defect.
+
+## Vocabulary
+
+An architectural boundary is a named group of code with one stable reason to change, such as a domain model, rendering subsystem, persistence adapter, compiler frontend, or deployable service. A folder often represents a boundary, but a folder is only evidence of one: the decisive fact is the responsibility its files jointly serve.
+
+A dependency edge is a directed relationship from code that relies on something to the code it relies on. For an import, `A -> B` means file A imports file B. The direction matters because changes to B can force changes in A.
+
+A boundary edge is the same relationship after file edges are grouped by their architectural boundaries. Ten imports from UI files into domain files form one `ui -> domain` boundary edge with ten pieces of file-level evidence.
+
+An allowed edge is a boundary dependency that agrees with a declared rule. A forbidden edge is an actual dependency that contradicts a declared rule about which responsibilities may rely on which others. Files being far apart or living under different directories does not by itself make the edge forbidden.
+
+A reciprocal dependency is a pair of boundary edges in both directions, such as `source -> parser` and `parser -> source`. It is a review signal because neither boundary can change independently, but it can be intentional when the named boundaries are really one subsystem or meet through a deliberately shared contract.
+
+A strongly connected component is a group of boundaries where every member can reach every other member through dependency edges. Its essential consequence is mutual change pressure: no member is directionally independent of the group. A component with many boundaries is evidence that the current names may not describe real separation.
+
+A cycle-break candidate is a boundary edge inside a dependency cycle whose small amount of file-level evidence makes it a plausible place to inspect first. It is not automatically the correct edge to remove; a single import can expose either an accidental shortcut or a legitimate contract that the boundary model failed to name.
+
+An architecture policy is the project-owned configuration that names boundaries and records dependency directions the maintainers are prepared to defend. Its rules are stronger than inferred folder conventions because the project explicitly chose them.
+
+An architecture ratchet is an enforcement rule that permits recorded existing debt while preventing new violations. It lets a large codebase improve incrementally without requiring a speculative rewrite before the policy becomes useful.
+
+Architectural coherence is the degree to which actual dependencies, named responsibilities, and declared dependency rules describe the same system. The tool should report the evidence needed to improve that alignment, not reduce coherence to a single score.
+
+## Why `drift` Is Not Enough
+
+Drift is movement away from a reference state or established pattern. A system can be statically incoherent without having changed recently, and it can change while remaining coherent. Therefore architecture needs a first-class report rather than being hidden inside `drift`.
+
+`codebaseiq architecture` owns the complete boundary graph and policy
+evaluation. `codebaseiq drift --architecture` reuses that report to show
+direct declared violations together with mapping coverage and report-only
+signals; it does not maintain a second policy engine.
+
+Before this work, the source-layer table in
+`src/queries/cleanup/drift-policy.ts` embedded repository-specific knowledge in
+a general-purpose command. An unrelated repository using folders such as
+`src/core` and `src/runtime` could therefore inherit codebaseiq's rules. That
+table has now been removed: drift consumes only explicit project
+configuration, and an unconfigured repository receives no architecture
+violations.
+
+## Configuration Model
+
+The first configuration shape should be small enough to understand without learning a policy language:
+
+```json
+{
+  "architecture": {
+    "boundaries": [
+      { "name": "domain", "paths": ["src/domain/**"] },
+      { "name": "source", "paths": ["src/source/**"] },
+      { "name": "runtime", "paths": ["src/runtime/**"] }
+    ],
+    "allowedDependencies": {
+      "domain": [],
+      "source": ["domain"],
+      "runtime": ["domain", "source"]
+    },
+    "requireCompletePolicy": true,
+    "requireAcyclic": true
+  }
+}
+```
+
+A boundary row names code; it does not yet prohibit anything. An `allowedDependencies` row is closed: when a row exists for `source`, every cross-boundary dependency not listed in that row is forbidden. A missing row means the project has not made a rule for that boundary yet. Same-boundary dependencies remain allowed.
+
+This distinction lets a large repository describe mature boundaries first while leaving emerging or disputed areas in discovery mode.
+
+`requireCompletePolicy` turns that gradual-discovery model into a finished
+contract: every configured boundary must have a closed row, including an empty
+row for a boundary that may depend on nothing. `requireAcyclic` independently
+forbids multi-boundary strongly connected components. A project should enable
+both only after the observed graph has been classified and repaired.
+
+`requireCompleteCoverage` gives boundary ownership normative force: every
+indexed, non-ignored file must match exactly one declared boundary. Without the
+flag, unmapped and ambiguous files remain visible coverage facts but cannot
+block work.
+
+`requireResolvedBoundaries` closes the gap the dependency rules leave open. Same-boundary
+dependencies are always allowed, so every edge inside a boundary is discarded
+before `requireAcyclic` runs — which means a boundary coarse enough to contain
+both sides of a cycle passes the check while saying nothing about the code
+inside it. The rule quotients each boundary by its sub-directories and requires
+that quotient to be acyclic too, so "no cycles" keeps its meaning as boundaries
+grow. It reports the narrowest internal edge as the inspection point, because a
+hidden cycle is usually one import against a dominant direction rather than a
+tangle.
+
+Four narrower rules close the remaining holes. `requireMinimalPolicy` rejects a
+declared allowance no edge uses, because `requireCompletePolicy` checks only
+that a row exists and a stale row widens the policy silently.
+`maxBoundaryFanOut` and global `maxBoundaryFiles` bound growth, since coarseness
+was otherwise caught only when it hid a cycle. A boundary-specific `maxFiles`
+overrides the global file ceiling only for that reviewed responsibility.
+`testPaths` brings test files back
+under enforcement — they are excluded from the compiler project and so from the
+index, which put them outside every rule — judging each test against the
+boundary of the code it covers, while still allowing it to reach anything that
+subject transitively reaches or that reaches the subject. And a boundary may set
+`subUnits: "file"` when its members form layers inside one directory.
+
+The failure it prevents is specific: this repository's own configuration
+declared 14 boundaries with `requireAcyclic: true` and reported zero cycles,
+while six of those boundaries — holding 85% of all files — each contained an
+internal cycle. The clean result was an artifact of granularity, not a property
+of the code.
+
+## What the Analyzer Should Report
+
+The report should preserve both policy truth and graph evidence:
+
+- mapped, unmapped, and ambiguously mapped files;
+- boundary edges with importer count, imported-file count, total file-edge count, and representative file edges;
+- forbidden edges, grouped by boundary pair rather than emitted as a flood of individual imports;
+- reciprocal boundary pairs;
+- strongly connected boundary components;
+- the narrowest internal edges to inspect first for each component;
+- policy coverage: which boundaries have closed dependency rows and which remain descriptive only.
+- resolved `export ... from` dependencies as well as ordinary imports, so
+  published barrel and package surfaces are governed;
+
+The output tiers should remain explicit:
+
+- **Direct finding:** an actual edge contradicts a declared rule, or a declared acyclicity rule is violated.
+- **Signal:** reciprocity, a large connected component, low policy coverage, an unmapped file, or a narrow cycle-break candidate.
+
+Inferred signals should not reduce health scores or block diffs until external calibration shows that acting on them reliably improves real codebases.
+
+## Applying This to an Existing Large Codebase
+
+The tool cannot discover the “best architecture” by optimizing graph shape. The best available architecture is the clearest model that preserves the system's real responsibilities and necessary behavior while reducing accidental change pressure. Finding it requires a staged investigation.
+
+### 1. Inventory the system's referents
+
+Read the repository guidance, package manifests, deployable entry points, routes, public exports, databases, message boundaries, tests, and build graph. Use codebaseiq to map consumers, dependencies, change surfaces, cycles, locality candidates, and historical co-change.
+
+This identifies what the code actually does and which units already behave as maintenance units.
+
+### 2. Name candidate boundaries
+
+Do not assume every top-level directory is a layer. A layer is a responsibility ordered by dependency direction, such as presentation over application over domain. A subsystem is a responsibility that owns an end-to-end capability, such as authentication or a compiler. A package is a publication or build unit. A service is an independently running unit.
+
+The architecture model may contain all four. The useful name is the one that predicts why its code changes and what it may depend on.
+
+### 3. Classify boundary maturity
+
+- A mature boundary is repeatedly expressed by code, documentation, tests, entry points, ownership, or history.
+- An emerging boundary has a coherent responsibility but inconsistent placement or dependencies.
+- An accidental boundary is mainly a convenience bucket, legacy pile, generated directory, or recent edit cluster.
+
+Only mature boundaries should receive closed dependency rules initially.
+
+### 4. Build a descriptive model first
+
+Add boundary path patterns without `allowedDependencies` rows. Run `codebaseiq architecture --json` to inspect mapping coverage, actual boundary edges, reciprocal pairs, and connected components.
+
+Revise names and path membership when the graph reveals that a supposed boundary has no independent responsibility or that one responsibility is split across several folders.
+
+### 5. Declare the rules supported by evidence
+
+For each mature boundary, state which other boundaries it is allowed to depend on and why. Record uncertain edges as unresolved decisions instead of silently allowing the entire current graph.
+
+Run the report again. A forbidden edge is now a testable disagreement between implementation and policy, not the tool's opinion about directory distance.
+
+### 6. Review and ratchet
+
+Run `codebaseiq architecture` after changing a declared boundary or one of its
+consumers. The report applies configured dependency rules exactly and cites the
+files that create each forbidden edge. Repositories that want a broader
+maintenance ratchet can record reviewed health findings with `codebaseiq health
+--write-baseline` and compare later scans with `codebaseiq health --baseline`.
+Neither command decides whether an arbitrary coding task is complete.
+
+### 7. Migrate narrow seams
+
+Start with a narrow edge whose few file dependencies cross a mature rule. Determine whether the right repair is to move code, invert a dependency, extract a genuinely shared contract, combine falsely separated boundaries, or revise the policy.
+
+Verify each slice with tests, typechecking, incomplete-migration checks,
+architecture analysis, and `diff-impact` before taking the next one.
+
+## Example: Vega 2.0
+
+For a codebase the size of Vega 2.0, the first pass should not invent a universal stack of layers. It should:
+
+1. identify workspace packages, applications, servers, public entry points, data stores, and major feature or compiler/rendering subsystems;
+2. map actual dependency traffic between those units;
+3. read the architecture and ownership claims already present in docs and package surfaces;
+4. classify candidate boundaries as mature, emerging, or accidental;
+5. configure the mature boundaries descriptively;
+6. inspect reciprocal pairs and large connected components with their file-edge breadth;
+7. close dependency rows only where the intended direction is supported;
+8. record reviewed violations and check each relevant change against the declared rules;
+9. migrate one narrow, high-confidence seam at a time.
+
+The initial result may be a mixture of layers and subsystems. That is preferable to forcing a neat diagram that contradicts the software. The model becomes stronger as verified migrations and maintenance history provide new facts.
+
+## Delivery Sequence
+
+### Slice 1: explicit measurement — implemented
+
+- Add architecture configuration types and validation.
+- Extract the reusable strongly-connected-component algorithm already embedded in `deep-chains`.
+- Add a pure architecture graph analyzer and `codebaseiq architecture`.
+- Extend the directory-architecture skill with the discover, declare, measure, and ratchet workflow.
+- Keep architecture findings distinct from ordinary code-smell scoring.
+
+### Slice 2: replace implicit drift policy — implemented
+
+- Move codebaseiq's source-boundary rules into its `.codebaseiq.json`.
+- Make drift consume architecture findings instead of repository-specific hardcoded folder rules.
+- Add `drift --architecture` as a summary view.
+- Preserve unused-import drift and keep sibling-pattern deviation opt-in.
+
+### Slice 3: baselines and enforcement — implemented locally; external calibration remains
+
+- Give architecture findings stable identities.
+- Add report-only health visibility.
+- Support an optional repository health baseline for teams that want a ratchet.
+- Calibrate on codebaseiq, Vega 2.0, Stable Management, and structurally different external repositories before any score deduction.
+
+### Slice 4: discovery assistance
+
+- Add candidate-boundary evidence that combines paths, entry points, public surfaces, dependency neighborhoods, and co-change history.
+- Have the skill produce a reviewable architecture draft, never silently write closed rules.
+- Measure whether suggested boundaries and repairs survive maintainer review and reduce future cross-boundary churn.
+
+## Success Criteria
+
+The architecture feature is effective when:
+
+- an unconfigured repository never inherits codebaseiq-specific rules;
+- a configured forbidden edge is reported with concrete import evidence;
+- broad and narrow boundary edges are distinguishable;
+- large cycles are summarized without flooding the user;
+- the agent can explain why each proposed boundary exists in the running system;
+- existing debt can be ratcheted without a rewrite;
+- acting on a recommendation improves ownership or dependency direction in externally reviewed codebases;
+- the tool is willing to say “the policy is incomplete” instead of manufacturing certainty.

package/docs/assets/codebaseiq-logo-dark.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="560" height="136" viewBox="0 0 560 136" role="img" aria-labelledby="title desc">
+  <title id="title">codebaseiq</title>
+  <desc id="desc">A minimal codebaseiq wordmark with a bright blue underscore cursor for dark backgrounds.</desc>
+  <style>
+    .wordmark {
+      fill: #F8FAFC;
+      font-family: Helvetica, Arial, sans-serif;
+      font-size: 58px;
+      font-weight: 700;
+      letter-spacing: 0;
+    }
+  </style>
+  <text
+    class="wordmark"
+    x="38"
+    y="83"
+    textLength="372"
+    lengthAdjust="spacingAndGlyphs"
+  >codebaseiq</text>
+  <rect x="430" y="76" width="50" height="8" rx="4" fill="#60A5FA" />
+</svg>

package/docs/assets/codebaseiq-logo.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="560" height="136" viewBox="0 0 560 136" role="img" aria-labelledby="title desc">
+  <title id="title">codebaseiq</title>
+  <desc id="desc">A minimal codebaseiq wordmark with a blue underscore cursor.</desc>
+  <style>
+    .wordmark {
+      fill: #111827;
+      font-family: Helvetica, Arial, sans-serif;
+      font-size: 58px;
+      font-weight: 700;
+      letter-spacing: 0;
+    }
+    .cursor {
+      fill: #2563EB;
+    }
+  </style>
+  <text
+    class="wordmark"
+    x="38"
+    y="83"
+    textLength="372"
+    lengthAdjust="spacingAndGlyphs"
+  >codebaseiq</text>
+  <rect class="cursor" x="430" y="76" width="50" height="8" rx="4" />
+</svg>

package/docs/locality-analyzer-design.md

@@ -0,0 +1,193 @@
+# Locality Analyzer Design
+
+This document designs the missing analyzer family identified during the analyzer inventory: a tool that evaluates where extracted code belongs. It is intentionally a design document, not a production implementation.
+
+The problem shows up most clearly after React or Vue large-component work. An agent can reduce a large file by extracting components, hooks, helpers, or composables, but it may dump all of them into a flat folder beside the original file. That can make the size metric better while making ownership, reuse, and navigation worse.
+
+## Core Concepts
+
+Code locality is the placement relation between a source unit and the files that use it. It concerns real files, directories, imports, consumers, tests, and package boundaries; its essential characteristic is that code belongs at the nearest stable home that all legitimate consumers can reach without making the API broader than the concept deserves.
+
+A source unit is a file, symbol, component, hook, composable, type, or helper that the analyzer can name and trace. It is the smallest unit whose placement can be judged from references, imports, and directory structure.
+
+A consumer set is the set of files or symbols that import, call, render, instantiate, or otherwise rely on a source unit. Its essential role is to reveal whether a unit is private to one place, shared within a feature, shared across a domain, or actually reusable across the application.
+
+An ownership boundary is a directory, package, route, feature, domain, or module boundary that indicates who should be allowed to change a unit. It is not just a path prefix; it is the codebase's visible grouping of reasons to change.
+
+An abstraction level is the height of a unit's meaning relative to product code. A button primitive, route panel, invoice calculation, GraphQL client, and test fixture can all be TypeScript functions or components, but they belong at different levels because they serve different kinds of callers.
+
+A shared folder is a directory whose name or import pattern says that multiple nearby units may depend on it. Its essential risk is that it can either preserve local reuse or become a dumping ground that erases ownership.
+
+A global shared folder is a repository-wide shared directory such as `src/shared`, `src/lib`, `src/components`, or `packages/shared`. Its essential risk is API inflation: code placed there becomes easier to depend on from anywhere, so the placement should require cross-feature or cross-package evidence.
+
+## Command Shape
+
+Proposed command:
+
+```sh
+codebaseiq locality-candidates [symbol-or-file]
+```
+
+Useful options:
+
+```sh
+codebaseiq locality-candidates apps/web/src/routes/HorsesView.tsx --json
+codebaseiq locality-candidates --scope apps/web/src --since HEAD~20
+codebaseiq locality-candidates --changed-only --base origin/main
+```
+
+The command should be report-only at first. Its action tier is contextual signal: it guides placement and review, but it should not move files automatically.
+
+## Inputs
+
+The analyzer should combine existing evidence rather than invent a separate world model.
+
+| Input                         | Source                                                                              | Why it matters                                                        |
+| ----------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Candidate source unit         | Explicit argument, changed files, large component/view pressure, extract candidates | Chooses what placement is being judged                                |
+| Consumer files and symbols    | `refs`, `imported-by`, `rdeps`, call graph, JSX/Vue render facts                    | Shows who actually uses the unit                                      |
+| Current path and import path  | filesystem path, import graph                                                       | Reveals whether the unit is already local, feature-shared, or global  |
+| Nearest common ancestor       | consumer file paths                                                                 | Finds the smallest directory all consumers share                      |
+| Feature and route roots       | path names such as `routes`, `pages`, `features`, `modules`, `domains`              | Distinguishes product areas from generic infrastructure               |
+| Package or workspace boundary | package manifests, tsconfig references, workspace layout                            | Prevents app-local concepts from leaking into shared packages         |
+| Test adjacency                | test file paths and references                                                      | Keeps test helpers near their tests unless production consumers exist |
+| Naming evidence               | source unit name, directory names, imported symbols                                 | Distinguishes product concepts from generic primitives                |
+| Historical co-change          | `co-change`, git history                                                            | Shows whether the unit changes with one feature or several            |
+| Existing local conventions    | sibling folder names and import patterns                                            | Avoids recommendations that fight the codebase's own organization     |
+
+## Placement Tiers
+
+| Tier                   | Recommendation                                         | Strong evidence                                                                           | Common mistake caught                                                                |
+| ---------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `same-file`            | Keep the unit in the original file.                    | One consumer, no independent tests, name only makes sense inside the parent.              | Extracting a private branch into a needless helper file.                             |
+| `sibling-private`      | Put it next to the parent in a private local folder.   | Two or more consumers under one page/component folder, no outside imports.                | Creating a route-local `components` folder under global `src/components`.            |
+| `feature-local-shared` | Put it under the nearest feature/module shared folder. | Consumers span files in one feature root but not outside it.                              | Moving feature-specific hooks into app-wide `shared`.                                |
+| `domain-shared`        | Put it under a domain or bounded context folder.       | Consumers cross feature roots but share domain nouns and co-change history.               | Duplicating business rules in several features or over-generalizing them into `lib`. |
+| `app-shared`           | Put it under app-level shared UI or utility space.     | Consumers cross domains inside one app and the name is generic enough for app reuse.      | Keeping a genuinely reusable primitive hidden inside one feature.                    |
+| `package-shared`       | Put it in a shared workspace package.                  | Consumers cross package/workspace boundaries, and package API ownership is intended.      | Importing across workspace internals or copying contracts between packages.          |
+| `no-extraction`        | Do not extract, or inline it back.                     | One consumer, weak name, no independent concept, extraction only satisfies a size metric. | Size-score gaming through thin files and local indirection.                          |
+
+The output should include confidence, reasons, counterevidence, and the exact consumer set.
+
+```json
+{
+  "candidate": "apps/web/src/features/horses/HorseStatusPanel.tsx",
+  "currentTier": "app-shared",
+  "recommendedTier": "feature-local-shared",
+  "confidence": "medium",
+  "consumers": ["apps/web/src/features/horses/HorseProfile.tsx", "apps/web/src/features/horses/HorseList.tsx"],
+  "nearestCommonAncestor": "apps/web/src/features/horses",
+  "reasons": [
+    "all production consumers are inside one feature root",
+    "candidate name uses the Horses domain noun",
+    "no package or cross-domain consumers found"
+  ],
+  "counterevidence": ["component name is presentational enough that future app-level reuse is possible"],
+  "suggestedHome": "apps/web/src/features/horses/components/HorseStatusPanel.tsx"
+}
+```
+
+## Analyzer Pairing
+
+The locality analyzer should not replace existing analyzers. It should complete their story.
+
+| Existing analyzer                                    | What it says today                                    | Locality companion question                                                                           |
+| ---------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `react-large-component-pressure`                     | This React component is too large.                    | If pieces are extracted, which ones are private, feature-local, or shared?                            |
+| `vue-large-view-pressure`                            | This Vue SFC is too large.                            | Should extracted child components/composables live beside the view, in the feature, or in app shared? |
+| `extract-candidates`                                 | This function contains a possible extraction cluster. | Would the extracted helper have one real owner or a broader consumer set?                             |
+| `react-hook-candidates`, `vue-composable-candidates` | Several components repeat behavior.                   | Is the hook/composable local to one feature or reusable across domains?                               |
+| `recent-duplicates`, `echo`                          | New code duplicates older code.                       | Which existing owner should the new code reuse, and would reuse widen the wrong API?                  |
+| `incomplete-migration`                               | A helper extraction stopped halfway.                  | Is the helper in the right place for all remaining call sites?                                        |
+| `co-change`                                          | Files move together historically.                     | Does history imply a hidden shared owner or only a local synchronization point?                       |
+
+## Algorithm Sketch
+
+1. Resolve the candidate to a file or symbol.
+2. Collect direct consumers through references, imports, render facts, and reverse dependencies.
+3. Remove consumers that are tests unless the candidate is test-only.
+4. Compute the nearest common ancestor of production consumers.
+5. Identify boundary markers in and above that ancestor: `app`, `apps`, `packages`, `routes`, `pages`, `features`, `modules`, `domains`, `shared`, `components`, `hooks`, `composables`, `lib`, `utils`, `services`, `stores`, and `contracts`.
+6. Classify the current home and the smallest legitimate home.
+7. Compare names from the candidate, directories, and consumers to decide whether the concept is domain-specific or generic.
+8. Check workspace/package boundaries to prevent cross-package leakage.
+9. Use co-change history as supporting evidence, not as a hard rule.
+10. Emit a recommendation only when the consumer set and boundary evidence agree.
+
+The first implementation can avoid automatic tree moves entirely. The valuable output is a review-grade explanation: "this extracted component is global today, but all consumers are in one feature, so feature-local shared is the smallest honest home."
+
+## Precision Rules
+
+The analyzer should prefer "no confident recommendation" over pretending all placement is obvious.
+
+Report `same-file` or `no-extraction` when a candidate has one consumer and no independent concept name.
+
+Report `sibling-private` when all consumers sit below one component, route, or view folder and no outside production import exists.
+
+Report `feature-local-shared` when consumers share a feature root and imports do not cross into other feature roots.
+
+Report `domain-shared` only when path names, symbol names, or co-change evidence show the same product domain across multiple feature roots.
+
+Report `app-shared` only when consumers cross domains inside one app and the unit is not named after one feature.
+
+Report `package-shared` only when consumers cross package boundaries and package exports make that sharing intentional.
+
+Downrank a recommendation when imports come only through barrels, tests are the only second consumer, the candidate name is generic but behavior is domain-specific, or the nearest common ancestor is the repo root.
+
+## Skill-First Option
+
+Before production implementation, this can ship as a bundled workflow skill.
+
+Proposed skill name:
+
+```text
+scip-locality-review
+```
+
+The skill would tell agents to run:
+
+```sh
+codebaseiq context <target> --full
+codebaseiq imported-by <symbol>
+codebaseiq rdeps <file>
+codebaseiq co-change <file> --full
+codebaseiq react-large-component-pressure <scope> --full
+codebaseiq vue-large-view-pressure <scope> --full
+```
+
+Then it would require the agent to answer:
+
+1. What is the exact consumer set?
+2. What is the nearest common owner all consumers share?
+3. Is the concept product-specific, feature-specific, app-generic, or package-level?
+4. Does the current path make the API wider than the consumer set requires?
+5. Would a move reduce imports and ownership confusion without creating a new global dumping ground?
+
+This is a good first step because it turns the product question into a repeatable checklist while we gather validation labels for the eventual command.
+
+## Validation Plan
+
+Use the validation corpus from `docs/analyzer-validation-protocol.md` and track the work under `docs/analyzer-validation-ledger.md`.
+
+For React, inspect Vega_2.0 large components and hook candidates. A true positive is a recommendation that would place an extracted unit closer to its actual consumers without hiding a real shared primitive.
+
+For Vue, inspect Stable_Management large views and composable candidates. A true positive is a recommendation that distinguishes route-local child components from feature-level composables and app-level UI primitives.
+
+For codebaseiq itself, inspect analyzer/helper extractions. A true positive is a recommendation that keeps detector-private helpers near their detector unless multiple detector families actually consume them.
+
+For Rust smoke coverage, run the command only after SCIP data supports the same source-unit questions. Until then, locality validation on Rust should be marked unsupported rather than failed.
+
+Validation result: `docs/validation/2026-06-21-locality-analyzer-validation-result.md` recommends a report-only or skill-first implementation, with `actionTier: "signal"` and explicit consumer-coverage caveats. React `.tsx` samples had usable `rdeps` evidence, but Vue SFC samples had weak reverse-dependency coverage, so the first implementation must not recommend concrete destinations unless exact consumers are known.
+
+## Score Integration
+
+Locality findings should not immediately reduce health like dead code. They are contextual signals.
+
+The health score can later use them as signal backlog pressure when they combine with other evidence:
+
+- Large component pressure plus globalized local children.
+- Extract candidates plus one-consumer helper files.
+- Recent duplicates plus a clear existing local owner.
+- Co-change clusters plus no shared owner directory.
+
+The score should not punish a single "could be more local" suggestion. It should punish repeated evidence that code organization is being flattened until ownership is unclear.