# OpenSpec Change: enterprise-overview

- **Change ID**: enterprise-overview
- **Package**: `@suaveplan/overview`
- **Category / plugin**: `devtools/tooling`
- **Target path**: `packages/devtools/tooling/overview`
- **Status**: PROPOSED
- **Date**: 2026-05-25
- **Design**: ./design.md
- **Spec delta**: ./specs/overview/spec.md
- **Reference docs**:
  - `/mnt/s/web/suaveplan/enterprise/overview.md` (enterprise contract)
  - `/mnt/s/web/suaveplan/packages/universal/overview/` (upstream — documentation-only bundle)
  - `scripts/folder-reorg/generate-manifest.ts` (genesis data model — the script
    explicitly notes "Replaces @suaveplan/overview"; this migration restores
    `overview` as the **library form** of that same data model)
  - `CLAUDE.md` foundation listing: "**overview** — machine-readable monorepo
    manifest with Zod schemas + graph utilities. Leaf."

---

## Summary

Migrate `@suaveplan/overview` onto genesis as a fresh, enterprise-grade
universal-tier **machine-readable monorepo manifest + graph-utilities library**.

The upstream main-branch package is a documentation bundle (≈90 ad-hoc `.md`
files plus a 27-line `postinstall.ts` that rewrites links). It carries no
runtime API, no tests, no schemas. That artefact is not enterprise-grade and
cannot be ported as-is.

The genesis form is a different package by name only: a typed library that
discovers every `packages/<category>/<plugin>/<pkg>/package.json` on disk,
parses each into a Zod-validated `PackageRecord`, exposes a typed
`SuavePlanManifest`, and provides graph utilities (forward / reverse adjacency,
topological order, cycle detection, transitive closure, leaf / root detection,
tier overlay, plugin and category roll-ups).

The same data model is currently produced ad-hoc by
`scripts/folder-reorg/generate-manifest.ts`, whose own header comment says
"Replaces @suaveplan/overview". This change re-introduces `overview` as the
**library** form of that script — single source of truth, exported as a typed
API, fully testable, with full enterprise instrumentation. The script can later
be refactored to consume the library; that refactor is out of scope for this
change.

---

## Current-state audit (genesis)

- Package directory does not exist on genesis.
- `STATUS.md` lists `@suaveplan/overview` as `–` (yet to migrate) under
  `devtools/tooling`.
- `scripts/folder-reorg/assignment.yml` line 665 confirms `tooling/overview`.
- `MANIFEST.md` does not yet contain an `@suaveplan/overview` row.
- `CLAUDE.md` foundation listing already describes the intended genesis shape
  (machine-readable manifest + Zod schemas + graph utilities) — this change
  realises that description.

**Verified by:** `ls packages/devtools/tooling/` (no `overview/`),
`grep -n "overview" STATUS.md` (one `–` row).

---

## Parity & enhancement checklist

The upstream package has no runtime surface, so this is functionally a
**genesis-original** library aligned to the data model already encoded by
`scripts/folder-reorg/generate-manifest.ts`. Every column below has a
compensating enhancement; nothing is dropped.

| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
| `.md` documentation bundle | ✅ docs-only | 🚫 dropped | Genesis ships per-package `README.md` + co-located `.md`; central doc bundle is obsolete. Replaced by **machine-readable manifest** as the cross-package index. |
| `postinstall.ts` link-rewriter | ✅ | 🚫 dropped | No `dist/*.md` to rewrite on genesis. Replaced by typed API. |
| Package discovery | 🚫 | ⬆️ NEW | `discoverPackages(root)` walks `packages/<category>/<plugin>/<pkg>/package.json`. |
| Zod schemas for every type | 🚫 | ⬆️ NEW | `PackageRecordSchema`, `SuavePlanManifestSchema`, `TierSchema`, `PluginSummarySchema`. |
| Tier inference | 🚫 | ⬆️ NEW | python → r3f → react → browser → server → universal (matches `openspec/specs/monorepo-structure/spec.md`). |
| Graph utilities | 🚫 | ⬆️ NEW | forward / reverse adjacency, topo sort, cycle detection, transitive closure, leaves, roots. |
| Plugin + category roll-ups | 🚫 | ⬆️ NEW | `byPlugin()`, `byCategory()`, `byTier()`. |
| Stable error codes via `defineCodes` | 🚫 | ⬆️ NEW | 6 `OVERVIEW.*` codes — each thrown from a real call site. |
| OpenTelemetry counters + histogram | 🚫 | ⬆️ NEW | 3 counters + 1 histogram. |
| `AbortSignal` support on async I/O | 🚫 | ⬆️ NEW | `discover` accepts `signal`; aborts mid-walk. |
| 100/100/100/100 Istanbul coverage | 🚫 | ⬆️ NEW | Test gate. |
| Co-located `.md` per implementation `.ts` | 🚫 | ⬆️ NEW | §4 docs rule. |
| Universal tier (zero Node-only run-time imports in library code) | n/a | ✅ | I/O helpers are server-tier and gated behind a sub-path entry; pure data + graph code is universal. |

No 🚫 entry without compensating ⬆️ enhancement.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `SuaveplanError` base + `defineCodes` |
| `@suaveplan/types` (`workspace:^`) | shared `Clock`-style types |
| `tslib` (`catalog:build`) | runtime helpers |
| `zod` (`catalog:forms`) | schemas |
| `@opentelemetry/api` (`catalog:observability`) | counters + histogram |

Dev deps: `@suaveplan/testing` (`workspace:^`), `vitest`,
`@vitest/coverage-istanbul`, `typescript`, `vite`, `vite-plugin-dts`.

---

## Public API surface (summary)

```ts
import {
  // schemas
  PackageRecordSchema,
  SuavePlanManifestSchema,
  TierSchema,
  // discovery (server sub-path: "@suaveplan/overview/discover")
  discoverPackages,
  // graph
  buildGraph,
  topologicalOrder,
  detectCycles,
  transitiveDependencies,
  transitiveDependents,
  leafPackages,
  rootPackages,
  // roll-ups
  byPlugin,
  byCategory,
  byTier,
  // errors
  OVERVIEW_CODES,
  OverviewError,
} from "@suaveplan/overview";

// Types
import type {
  PackageRecord,
  SuavePlanManifest,
  Tier,
  PluginSummary,
  WorkspaceGraph,
} from "@suaveplan/overview";
```

---

## File layout

```text
packages/devtools/tooling/overview/
  package.json, tsconfig.lib.json, vite.config.ts, vitest.config.ts, README.md
  src/
    index.ts
    types/types.ts, types.md
    errors/errors.{ts,md,test.ts}
    schemas/schemas.{ts,md,test.ts}
    tier/tier.{ts,md,test.ts}
    discover/discover.{ts,md,test.ts}
    graph/graph.{ts,md,test.ts}
    rollups/rollups.{ts,md,test.ts}
    telemetry/telemetry.{ts,md,test.ts}
  tests/setup/polyfills.ts
```

---

## Impact

### Affected dependents

- No `@suaveplan/*` consumer currently imports `@suaveplan/overview` on
  genesis. The library is consumable by `scripts/folder-reorg/generate-manifest.ts`
  in a future cleanup change (out of scope here).
- Downstream tools (CLI dashboards, dependency-graph visualisers, ratings
  dashboards) can adopt the typed API instead of re-implementing manifest
  discovery.

**Breaking changes**: none (new package on genesis; upstream was docs-only
with no runtime API).