OpenSpec Change: enterprise-overview

Change ID: enterprise-overview
Package: @suaveplan/overview
Category: universal
Target path: universal/docs/overview
Status: PROPOSED
Date: 2026-04-19
Reference spec: /mnt/s/web/suaveplan/enterprise/overview.md

Summary

Documentation-only package publishing a curated, machine-readable description of the whole monorepo: every package name, one-line purpose, category, dependency edges, layer index, and current genesis status. Consumed by dashboards, README generators, and AI agents (including openspec/AGENTS.md tooling). Zero runtime code — ships a typed JSON manifest plus a validator.

Current-state audit (genesis)

Does not exist on genesis. Genesis currently has CLAUDE.md / FOLDERS.yml as the authoritative monorepo map; this package turns them into a consumable data artifact.

Dependencies

Workspace: none (leaf)
External (via catalog): zod → catalog:forms
Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata → catalog:testing

Preserved public surface

Data artifact

manifest.json — top-level { generatedAt, version, categories: Category[], packages: Package[] }
Category — { slug, title, parentCategory?, description }
Package — { name, category, path, layer, summary, dependsOn: string[], status: 'genesis' | 'pending' | 'archived', version }

Runtime API

loadManifest(path?) — load and Zod-validate a manifest file.
validateManifest(obj) — ManifestSchema.parse.
layerFor(name, manifest) — returns the topological layer (0 = leaves).
dependentsOf(name, manifest), dependenciesOf(name, manifest) — graph walkers.
ManifestSchema, CategorySchema, PackageSchema — Zod schemas.

New genesis additions

Codes via defineCodes: OVERVIEW.MANIFEST_INVALID, OVERVIEW.CYCLE_DETECTED, OVERVIEW.PACKAGE_NOT_FOUND.
Property-based tests (fast-check): cycle detection on random DAGs, topo-layer correctness.
Build step reads FOLDERS.yml + every workspace package.json and regenerates manifest.json at the repo root.

Impact

Adds one new package: universal/docs/overview
Adds one new spec capability: overview
Does not depend on anything.

2.2 KiB Raw Blame History