Encore OS — Documentation

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:

The barrel must be listed in docs/architecture/integrations/PLATFORM_INTEGRATION_LAYERS.md with a status of ✅ Complete.
The barrel must currently have zero unused-export findings (otherwise pre-existing debt would be masked).
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:

Triage each unused export: is it documented in the layer’s README/integration doc?
If yes → annotate with /** @expected-unused */ + a one-line note pointing to the doc.
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:

A React.lazy() target — route files commonly use lazy(() => import('@/cores/.../PageName')).
A barrel re-export target — files re-exported from src/cores/*/index.ts and src/platform/**/index.ts.
A Supabase Edge Function entry/shared module — keep supabase/functions/*/index.ts and validate non-_shared helpers.
A fixture/mock/factory — especially under tests/mocks/**, tests/e2e/fixtures/**, and tests/utils/mock-factories.ts.
A script invoked by npm or CI — verify package.json scripts and workflow usage.
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

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: Fix in src/platform/table-v2/index.ts:

export {
  type UseTableUrlStateOptions,
  useTableUrlState,
} from '@/platform/router/useTableUrlState';

Phase 2 exit criteria: circularDependencies: 0.

Verification

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

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

Select one module or barrel.
Classify each item as remove, investigate, or keep.
Apply small batches (10-20 files or one barrel at a time).
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:

Added explicit entry points: src/routes/**/lazy-pages.ts and src/main.tsx.
Added Deno npm:*/jsr:* specifiers to ignoreDependencies for Supabase function imports.
Added ignoreExportsUsedInFile: true to reduce same-file export noise.
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.

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.
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)

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
Fallow configuration overview
Fallow adoption guide
Dead code analysis explanation
Rules & severity
Architecture boundaries
Skill file: .cursor/skills/dead-code-audit/SKILL.md
Config: .fallowrc.json

​Canonical accuracy mode: production

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

​Script wiring

​Why two baselines?

​Barrel-noise / Public-API suppression policy

​Default position

​When suppression is justified

​Currently suppressed surfaces (forward-protection only)

​How to expand the suppression set responsibly

​Why unused-types is off

​Current production findings (2026-05-08)

​False-positive patterns to verify before deletion

​Phased remediation timeline

​Phase 1: Dependencies (lowest risk)

​1a) Unused dependencies (3)

​1b) Type-only dependencies (2)

​Verification

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

​Verification

​Phase 3: Duplicate exports (37 pairs)

​Pattern A: type duplicated between consumer and type barrel

​Pattern B: same concept defined across multiple type files

​Pattern C: utility exports duplicated across modules

​Verification

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

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

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

​Batch workflow

​Config changes made

​CI promotion path

​Re-baseline workflow (after each phase)

​References

Canonical accuracy mode: production

Production-mode baseline (2026-05-08)

Script wiring

Why two baselines?

Barrel-noise / Public-API suppression policy

Default position

When suppression is justified

Currently suppressed surfaces (forward-protection only)

How to expand the suppression set responsibly

Why `unused-types` is `off`

Current production findings (2026-05-08)

False-positive patterns to verify before deletion

Phased remediation timeline

Phase 1: Dependencies (lowest risk)

1a) Unused dependencies (3)

1b) Type-only dependencies (2)

Verification

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

Verification

Phase 3: Duplicate exports (37 pairs)

Pattern A: type duplicated between consumer and type barrel

Pattern B: same concept defined across multiple type files

Pattern C: utility exports duplicated across modules

Verification

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

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

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

Batch workflow

Config changes made

CI promotion path

Re-baseline workflow (after each phase)

References