> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dead Code Remediation Plan

> Generated: 2026-05-06 Last revalidated: 2026-05-08 (deep-pass production-mode baseline) Tool: Fallow v2.66.1 Config: .fallowrc.json (validated against official…

**Generated:** 2026-05-06
**Last revalidated:** 2026-05-08 (deep-pass production-mode baseline)
**Tool:** Fallow v2.66.1
**Config:** `.fallowrc.json` (validated against official docs)

> **Note (script rename):** the raw-fallow `check:dead-code*` npm scripts referenced
> below were removed and superseded by the unified orchestrator — use `npm run deadcode`
> (and `npm run deadcode:ci` for the CI gate). The Fallow flags/config described here are
> unchanged; only the npm entry points were consolidated.

***

## Canonical accuracy mode: production

As of 2026-05-08 the canonical accuracy gate is **production mode** (`fallow dead-code --production`). This excludes test/story/dev files so "used by tests only" code is correctly flagged. Dev-inclusive runs remain available as `check:dead-code:dev` for investigating false-positive routes through test fixtures.

### Production-mode baseline (2026-05-08)

| Category               | Count |
| ---------------------- | ----: |
| Total issues           | 4,563 |
| Unused files           |   663 |
| Unused exports         | 3,838 |
| Unused dependencies    |     3 |
| Duplicate exports      |    37 |
| Circular dependencies  |    20 |
| Type-only dependencies |     2 |

Stored in:

* `regression.baseline` inside `.fallowrc.json` (used by `--fail-on-regression`)
* `.fallow-baseline.json` (snapshot used by `--baseline` for added/removed/unchanged diffs)
* `.fallow-baseline.dev.legacy.json` — prior dev-mode snapshot, retained for historical reference

### Script wiring

* `npm run check:dead-code` → `fallow dead-code --production` (default audit)
* `npm run check:dead-code:dev` → dev-inclusive (test files count as consumers)
* `npm run check:dead-code:baseline` → production-mode compact diff vs snapshot baseline
* `npm run check:dead-code:regression` → JSON-parsed gate; exit 0 only when `regression.exceeded == false`
* `npm run check:dead-code:ci` → alias for `:regression`

### Why two baselines?

| Baseline                                        | Purpose                                             | Format         |
| ----------------------------------------------- | --------------------------------------------------- | -------------- |
| `regression.baseline` (inside `.fallowrc.json`) | Hard CI gate: total-count regression                | counts only    |
| `.fallow-baseline.json`                         | Diff view of which specific issues are new vs known | per-issue list |

***

## Barrel-noise / Public-API suppression policy

Mass-suppressing barrel re-exports hides genuine debt and is therefore forbidden. The policy below governs when and how to mark exports as intentionally retained.

### Default position

**Unused exports are debt.** The default action for a `unused-export` finding is to delete the export (or its source file) after consumer verification. Do not add suppression comments or `ignoreExports` entries to silence a finding you don't intend to fix.

### When suppression is justified

Suppression is allowed only for exports that are part of a **documented public API contract** (per `docs/architecture/integrations/PLATFORM_INTEGRATION_LAYERS.md`) and that exist intentionally to be consumed externally — even when no current consumer exists.

| Mechanism                                                   | When to use                                                                                                                                                                                                 |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ignoreExports` in `.fallowrc.json` with `"exports": ["*"]` | A barrel `index.ts` is documented as the canonical public surface for a Platform Integration Layer **and** currently has zero unused-export findings. Adds forward protection without masking present debt. |
| `/** @expected-unused */` JSDoc tag on a single export      | A specific symbol is documented in the layer's README/contract as part of the public surface but has no consumer yet. Fallow will alert if the symbol later becomes used (proving the contract claim).      |
| `// fallow-ignore-next-line unused-export`                  | Last resort for one-off false positives. Requires a justifying comment on the same or preceding line.                                                                                                       |

### Currently suppressed surfaces (forward-protection only)

The following barrels carry zero unused-export findings today, are documented as Platform Integration Layer public contracts, and are pre-marked to prevent future regressions from being masked behind "we'll consume it later":

* `src/platform/types/index.ts` — shared `EncounterContext`, `ChargeContext`, `DiagnosisReference` types (cross-core)
* `src/platform/csv/index.ts` — shared CSV parsing primitives for bulk imports
* `src/platform/scheduling/index.ts` — encounter/appointment context (CL-04, CL-14, CL-24)
* `src/platform/email-signatures/index.ts` — PF-86 org/user signature service
* `src/platform/quota/index.ts` — PF-43 tenant resource quotas

Adding to this list requires:

1. The barrel must be listed in `docs/architecture/integrations/PLATFORM_INTEGRATION_LAYERS.md` with a status of `✅ Complete`.
2. The barrel must currently have zero unused-export findings (otherwise pre-existing debt would be masked).
3. The PR adding it must call out the rationale and link to the layer's documentation.

### How to expand the suppression set responsibly

If a documented PIL barrel currently has unused exports (e.g. `@/platform/forms`, `@/platform/telephony`, `@/platform/gestures`), do **not** add it to `ignoreExports` wholesale. Instead:

1. Triage each unused export: is it documented in the layer's README/integration doc?
2. If yes → annotate with `/** @expected-unused */` + a one-line note pointing to the doc.
3. If no → delete the export.

Once the barrel reaches zero unused findings via this targeted process, it qualifies for the `ignoreExports` forward-protection list above.

### Why `unused-types` is `off`

Type aliases and interfaces are frequently re-exported as part of API contracts and are erased at runtime. Tracking them per export creates noise without bundle-impact value. The `unused-types` rule remains `off` and should not be re-enabled without a separate proposal.

***

## Current production findings (2026-05-08)

This plan is based on the production-mode run (`fallow dead-code --production --format json --quiet`) revalidated on 2026-05-08 and triaged in `reports/active/fallow-production-baseline-triage-2026-05-08.md`.

| Category               | Count |
| ---------------------- | ----: |
| Total issues           | 4,563 |
| Unused files           |   663 |
| Unused exports         | 3,838 |
| Unused dependencies    |     3 |
| Type-only dependencies |     2 |
| Duplicate exports      |    37 |
| Circular dependencies  |    20 |
| Unresolved imports     |     0 |
| Unlisted dependencies  |     0 |
| Boundary violations    |     0 |

***

## False-positive patterns to verify before deletion

Before removing any file, confirm it is **not**:

1. **A `React.lazy()` target** — route files commonly use `lazy(() => import('@/cores/.../PageName'))`.
2. **A barrel re-export target** — files re-exported from `src/cores/*/index.ts` and `src/platform/**/index.ts`.
3. **A Supabase Edge Function entry/shared module** — keep `supabase/functions/*/index.ts` and validate non-`_shared` helpers.
4. **A fixture/mock/factory** — especially under `tests/mocks/**`, `tests/e2e/fixtures/**`, and `tests/utils/mock-factories.ts`.
5. **A script invoked by npm or CI** — verify `package.json` scripts and workflow usage.
6. **A runtime dynamic asset** — service worker (`public/sw-push.js`) and chatbot embed assets.

***

## Phased remediation timeline

### Phase 1: Dependencies (lowest risk)

**Goal:** Resolve the 5 dependency findings first (fastest low-risk reduction).

#### 1a) Unused dependencies (3)

| Package          | Action                                | Rationale                                                                                              |
| ---------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `@ai-sdk/openai` | **Investigate -> remove or suppress** | Runtime standard is Lovable AI Gateway/OpenRouter; verify no direct import usage before removal.       |
| `valibot`        | **Remove**                            | Project standard is Zod. Remove if no imports remain.                                                  |
| `workbox-window` | **Investigate**                       | Likely runtime/PWA-related. Keep only if genuinely consumed; otherwise remove or document suppression. |

#### 1b) Type-only dependencies (2)

| Package                  | Action                        | Rationale                           |
| ------------------------ | ----------------------------- | ----------------------------------- |
| `@rrweb/types`           | **Move to `devDependencies`** | Detected as type-only import usage. |
| `@supabase/postgrest-js` | **Move to `devDependencies`** | Detected as type-only import usage. |

**Phase 1 exit criteria:** `unusedDependencies: 0` and `typeOnlyDependencies: 0` in `.fallowrc.json` `regression.baseline`.

#### Verification

```bash theme={null}
npm run check:dead-code:regression
npm run test:baseline
```

***

### Phase 2: Circular dependencies (single high-leverage fix)

**Goal:** Eliminate all 20 cycles with one import-path change.

All 20 cycles follow this path:

```mermaid theme={null}
flowchart LR
  pageNode["src/cores/core/pages/Page.tsx"]
  tableV2Node["src/platform/table-v2/index.ts:72"]
  routerBarrelNode["src/platform/router/index.ts:13"]
  slugNode["src/platform/router/SlugNestedContent.tsx"]
  routesNode["src/routes/core.tsx"]
  pageNode --> tableV2Node --> routerBarrelNode --> slugNode --> routesNode --> pageNode
```

Fix in `src/platform/table-v2/index.ts`:

```ts theme={null}
export {
  type UseTableUrlStateOptions,
  useTableUrlState,
} from '@/platform/router/useTableUrlState';
```

**Phase 2 exit criteria:** `circularDependencies: 0`.

#### Verification

```bash theme={null}
npm run check:dead-code:regression
npm run typecheck
```

***

### Phase 3: Duplicate exports (37 pairs)

**Goal:** Consolidate duplicate symbols into a single canonical source per concept.

#### Pattern A: type duplicated between consumer and type barrel

| Example                                                                  | Canonical                                                   |
| ------------------------------------------------------------------------ | ----------------------------------------------------------- |
| `AppVersionInfo` (`platform/pwa/components` + `platform/pwa/hooks`)      | Keep component-local type and remove duplicate hook export. |
| `DepartmentOption` (`platform/workforce/types.ts` + `useDepartments.ts`) | Keep `types.ts` as canonical and import from there.         |
| `FAModuleSettings`/`FMModuleSettings` (`hooks` + `types/index.ts`)       | Keep canonical `types/index.ts` definitions.                |

#### Pattern B: same concept defined across multiple type files

| Example                                                                                | Canonical                                     |
| -------------------------------------------------------------------------------------- | --------------------------------------------- |
| `AssertionResult` (`fw/types/test-cases.ts` + `fw/types/test-scenarios.ts`)            | Move to one shared FW type file.              |
| `ConditionOperator` (FW files + `platform/forms/types.ts`)                             | Keep `platform/forms/types.ts`, import in FW. |
| `CrossFieldValidation` (`platform/conditional-logic/types.ts` + `validation/types.ts`) | Keep in `validation/types.ts`.                |

#### Pattern C: utility exports duplicated across modules

| Example                                                         | Canonical                                                     |
| --------------------------------------------------------------- | ------------------------------------------------------------- |
| `exportToCSV/exportToExcel/exportToPDF` (FA + platform reports) | Keep platform report exports, have FA consume platform layer. |
| `coerceToDate/coerceToNumber` (operators + validator)           | Keep in `utils/operators.ts`.                                 |
| `InfoTooltip` (`platform/help` + `shared/components`)           | Keep one shared implementation and re-route importers.        |

**Phase 3 exit criteria:** `duplicateExports: 0`.

#### Verification

```bash theme={null}
npm run typecheck
npm run check:dead-code:regression
```

***

### Phase 4: Long-tail cleanup (unused exports + unused files)

**Goal:** Burn down the largest barrel-heavy export noise first, then trim true unused files in small verified batches.

#### 4a) Top unused-export concentrations (production mode)

| File                                            | Count |
| ----------------------------------------------- | ----: |
| `src/cores/it/hooks/index.ts`                   |   100 |
| `src/platform/conditional-logic/index.ts`       |    97 |
| `src/cores/lo/hooks/index.ts`                   |    86 |
| `src/platform/ai/index.ts`                      |    74 |
| `src/cores/gr/components/index.ts`              |    71 |
| `src/platform/dashboard/index.ts`               |    59 |
| `src/platform/telephony/index.ts`               |    57 |
| `src/platform/templates/index.ts`               |    56 |
| `src/platform/forms/index.ts`                   |    55 |
| `src/cores/cl/types/index.ts`                   |    53 |
| `src/cores/fm/hooks/index.ts`                   |    51 |
| `src/platform/page-layouts/index.ts`            |    48 |
| `src/platform/onboarding/index.ts`              |    45 |
| `src/platform/table-v2/index.ts`                |    43 |
| `src/cores/hr/components/ats/index.ts`          |    42 |
| `src/platform/health/index.ts`                  |    39 |
| `src/cores/hr/benefits/hooks/index.ts`          |    38 |
| `src/platform/messaging/index.ts`               |    38 |
| `src/platform/tasks/index.ts`                   |    38 |
| `src/platform/documents/index.ts`               |    37 |
| `src/platform/theming/index.ts`                 |    36 |
| `src/platform/gestures/index.ts`                |    32 |
| `src/platform/field-config/index.ts`            |    29 |
| `src/platform/permissions/index.ts`             |    28 |
| `src/platform/onboarding/integrations/index.ts` |    27 |

Use the suppression policy above: only keep truly documented public API exports (`@expected-unused` or qualified `ignoreExports`), delete the rest.

#### 4b) Unused files by highest-volume module (production mode, 663 total)

| Module                  | Count |
| ----------------------- | ----: |
| `src/cores/hr`          |   119 |
| `src/cores/fw`          |    69 |
| `src/cores/pm`          |    66 |
| `src/cores/cl`          |    52 |
| `src/cores/rh`          |    37 |
| `src/cores/ce`          |    36 |
| `src/cores/gr`          |    30 |
| `src/platform/ai`       |    26 |
| `src/cores/it`          |    21 |
| `src/cores/fa`          |    20 |
| `src/cores/lo`          |    15 |
| `src/cores/fm`          |    15 |
| `src/platform/wizards`  |    13 |
| `src/shared/lib`        |    12 |
| `src/platform/table-v2` |    10 |
| Remaining modules       |   122 |

#### Batch workflow

1. Select one module or barrel.
2. Classify each item as **remove**, **investigate**, or **keep**.
3. Apply small batches (10-20 files or one barrel at a time).
4. Re-run verification and baseline update.

**Phase 4 exit criteria (target):** `unusedFiles <= 200`, `unusedExports <= 800`.

***

## Config changes made

The `.fallowrc.json` was updated during this audit with the following improvements:

1. Added explicit entry points: `src/routes/**/lazy-pages.ts` and `src/main.tsx`.
2. Added Deno `npm:*`/`jsr:*` specifiers to `ignoreDependencies` for Supabase function imports.
3. Added `ignoreExportsUsedInFile: true` to reduce same-file export noise.
4. Expanded rule severities (`unused-dependencies`, `duplicate-exports`, `circular-dependencies`, `boundary-violation`, `stale-suppressions`, etc.).

***

## CI promotion path

Current state: `.github/workflows/build.yml` runs `npm run check:dead-code:ci` in `non-blocking-analysis` with `continue-on-error: true`.

1. After Phase 1 + Phase 2 land (deps/type-only clean, cycles eliminated), make dead-code regression blocking by removing `continue-on-error: true` from the dead-code step.
2. After Phase 3 duplicate-export consolidation, remove `continue-on-error` from the `non-blocking-analysis` job and enforce dead-code gating in CI.

***

## Re-baseline workflow (after each phase)

```bash theme={null}
npx fallow dead-code --production --save-regression-baseline
git diff -- .fallowrc.json
git diff -- .fallow-baseline.json
npm run check:dead-code:regression
```

`.fallow-baseline.dev.legacy.json` remains historical reference only (gitignored).

***

## References

* [Fallow documentation](https://docs.fallow.tools)
* [Fallow configuration overview](https://docs.fallow.tools/configuration/overview)
* [Fallow adoption guide](https://docs.fallow.tools/adoption)
* [Dead code analysis explanation](https://docs.fallow.tools/explanations/dead-code)
* [Rules & severity](https://docs.fallow.tools/configuration/rules)
* [Architecture boundaries](https://docs.fallow.tools/configuration/boundaries)
* Skill file: `.cursor/skills/dead-code-audit/SKILL.md`
* Config: `.fallowrc.json`