Initial Commit

openspec/archive/2026-04-19-enterprise-overview/proposal.md

@@ -0,0 +1,49 @@
+# 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.

openspec/archive/2026-04-19-enterprise-overview/specs/overview/spec.md

@@ -0,0 +1,24 @@
+# Capability Spec: overview
+
+**Package**: `@suaveplan/overview`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### OVR-01 — Manifest schema
+`ManifestSchema` MUST validate `{ generatedAt: ISO-8601 string, version: semver, categories: Category[], packages: Package[] }`. Every `Package.dependsOn` entry MUST reference an existing `Package.name`. Duplicate names MUST be rejected with `OVERVIEW.MANIFEST_INVALID`.
+
+### OVR-02 — Topological layers
+`layerFor(name, manifest)` MUST return a non-negative integer such that a package with `dependsOn = []` has layer 0, and every other package's layer is one more than the max of its dependencies' layers. If a cycle is detected, `layerFor` MUST throw `OVERVIEW.CYCLE_DETECTED`.
+
+### OVR-03 — Graph walkers
+`dependenciesOf(name, manifest)` MUST return the transitive closure of a package's `dependsOn` edges. `dependentsOf(name, manifest)` MUST return the transitive closure of the reverse edges. Both MUST throw `OVERVIEW.PACKAGE_NOT_FOUND` for unknown names.
+
+### OVR-04 — Generator contract
+The generator script MUST scan every workspace `package.json`, merge with `FOLDERS.yml`, and produce a deterministic `manifest.json` at the repo root. Output MUST be stable: re-running the generator with no workspace changes MUST produce byte-identical output.
+
+### OVR-05 — Validation at the boundary
+`loadManifest(path?)` MUST read and `ManifestSchema.parse` the file. Malformed JSON MUST surface as `OVERVIEW.MANIFEST_INVALID` with the path and parser reason in context.

openspec/archive/2026-04-19-enterprise-overview/tasks.md

@@ -0,0 +1,31 @@
+# Tasks: enterprise-overview
+
+## 1. Scaffold
+- [x] 1.1 Create `universal/docs/overview/` with package.json, tsconfig(.lib).json, vite+vitest configs, README skeleton.
+- [x] 1.2 100/100/100/100 coverage thresholds; istanbul provider.
+- [x] 1.3 Cross-cutting guard tests.
+- [x] 1.4 Add to root `CLAUDE.md`, `README.md`, `FOLDERS.yml`.
+
+## 2. Schemas + errors
+- [x] 2.1 `src/schemas/manifest.schema.ts` — `CategorySchema`, `PackageSchema`, `ManifestSchema`.
+- [x] 2.2 `src/errors/overview-error.ts` — codes `OVERVIEW.MANIFEST_INVALID`, `OVERVIEW.CYCLE_DETECTED`, `OVERVIEW.PACKAGE_NOT_FOUND`.
+
+## 3. Runtime API
+- [x] 3.1 `src/load/load.ts` — `loadManifest`, `validateManifest`.
+- [x] 3.2 `src/graph/graph.ts` — `layerFor`, `dependentsOf`, `dependenciesOf`; cycle detection.
+- [x] 3.3 Co-located `.md` docs.
+- [x] 3.4 Property tests: random DAG → topo layers monotone; cycles detected.
+
+## 4. Generator script
+- [x] 4.1 `scripts/generate-manifest.ts` — walks workspace, parses `FOLDERS.yml`, writes `manifest.json` at repo root.
+- [x] 4.2 CI task + pre-commit hook to regenerate on `package.json` change.
+
+## 5. Docs + exports
+- [x] 5.1 Subpath exports per feature.
+- [x] 5.2 Root `README.md`.
+
+## 6. Benchmarks
+- [x] 6.1 `src/__benchmarks__/layer.bench.ts` — layerFor on a 300-package manifest.
+
+## 7. Ship gate
+- [x] 7.1 Pre-ship verification sequence green; fold spec; archive.