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

# ADR-022: Tear down the inert workspace-packages + microfrontends overlay

> ADR accepting teardown of the inert workspace-packages + microfrontends overlay (supersedes ADR-016/ADR-017); removes never-activated scaffolding.

**Status:** Accepted
**Date:** 2026-05-25
**Participants:** Jeremy Bloom (project owner)
**Supersedes:** [`ADR-016`](/architecture/decisions/ADR-016-workspace-packages-overlay), [`ADR-017`](/architecture/decisions/ADR-017-microfrontends-pwa-scoping)
**Related:** [`ADR-008`](/architecture/decisions/ADR-008-vite-spa-vs-ssr), [`ADR-010`](/architecture/decisions/ADR-010-core-pf-dependency-boundary), [`ADR-013`](/architecture/decisions/ADR-013-pwa-strategy), constitution §1

***

## Context

Two related pieces of forward-looking scaffolding were added on 2026-04-22 (PR #137/#138 follow-ups) and never activated:

1. **Workspace-packages overlay (ADR-016).** Empty `packages/core-*`, `packages/platform`, and `packages/shared` stubs — `package.json` files only, with an `encoreos.sourceDirectory` pointer back to `src/`. No source was moved. A metadata-layer audit (`scripts/audit/audit-package-boundaries.ts`, npm `audit:package-boundaries`, CI gate in `build.yml`) enforced the declared dependency graph, and `scripts/dev/generate-core-package-jsons.mjs` regenerated the stubs.

2. **Microfrontends overlay (ADR-017).** A root `microfrontends.json` routing map plus empty `packages/encoreos-app` / `packages/encoreos-public` placeholders, a validation script (`scripts/audit/validate-microfrontends-config.ts`, npm `audit:microfrontends`), a runbook, and an activation checklist. The scaffolding commit was explicitly titled *"Vercel Microfrontends scaffolding (inert until activation)."*

### Evidence both overlays are inert (gathered 2026-05-25)

* **Zero `@encoreos/*` imports** anywhere in `src/`, `tests/`, or `tools/`. The app resolves everything through the `@/` path alias (`tsconfig.app.json`, `vite.config.ts`). The workspace package names are never consumed.
* Turborepo tasks are all root-scoped (`//#…`); no workspace package is a build target.
* `vercel.json` contains **no** microfrontends/app/public configuration. The `@vercel/microfrontends` dependency is **not installed**. The vite plugin is "intentionally absent" (comment-only).
* ADR-017 status was **Proposed** ("becomes Accepted on Phase 3 activation"); the activation checklist never ran.

The overlays therefore add cognitive load — confusing `packages/` tree, near-identical boilerplate, two extra audit gates, a routing file, a runbook — while having **no runtime or build effect today**.

## Decision

Remove both overlays and return to the single-app monolith of record:

* Delete `packages/core-*`, `packages/platform`, `packages/shared`, `packages/encoreos-app`, `packages/encoreos-public`, and the orphaned `packages/encore-spec` (which had only a stray `node_modules/`). **Keep `packages/docs`** (the real Docusaurus site).
* Delete `microfrontends.json` and its validator (`scripts/audit/validate-microfrontends-config.ts`, npm `audit:microfrontends`).
* Delete `scripts/audit/audit-package-boundaries.ts`, `scripts/dev/generate-core-package-jsons.mjs`, the npm scripts `audit:package-boundaries` / `packages:regenerate-cores`, and the `audit:package-boundaries` step in `.github/workflows/build.yml`.
* Prune the removed members from the root `package.json` `workspaces` array.
* Remove the now-orphaned docs (`WORKSPACE_PACKAGES.md`, `MICROFRONTENDS_RUNBOOK.md`, `MICROFRONTENDS_ACTIVATION_CHECKLIST.md`) and their `docs.json` nav entries; clean the microfrontends activation comments from `vite.config.ts`.

Architecture boundaries remain enforced by the **import-scan layer** (`check-architecture`), which was always the primary gate; only the redundant package-metadata layer is retired.

## Consequences

**Positive**

* `packages/` shrinks to the one real package (`docs`); the confusing empty-stub tree is gone.
* Two CI/audit gates and their scripts retire; the dependency graph is enforced by the import-scan that already runs.
* No more "why are these packages empty?" onboarding friction.

**Negative / accepted**

* The metadata-layer boundary check (a second enforcement layer over import-scan) is gone. Acceptable: it never caught anything import-scan didn't, and nothing imported the packages.
* A future modular/microfrontends migration starts clean rather than from this scaffolding. Git history (this ADR + ADR-016/017 + the original commits) preserves the prior design for revival.

## References

* Supersedes [`ADR-016`](/architecture/decisions/ADR-016-workspace-packages-overlay), [`ADR-017`](/architecture/decisions/ADR-017-microfrontends-pwa-scoping)
* Cleanup design: `docs/superpowers/specs/2026-05-25-scripts-packages-cleanup-design.md`
* Cleanup plan: `docs/archive/superpowers-plans-2026-05/2026-05-25-scripts-packages-cleanup.md`