diff --git a/CLAUDE.md b/CLAUDE.md index 8dd4592..c4c29fd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,7 +72,7 @@ Every feature has a `src/feature.manifest.ts` declaring its use cases, audits, p | **CI drift gate** (`pnpm conformance`) | ~120s | orphan event consumers across features | | **Fallow** (`pnpm fallow`) | ~30–60s | dead exports / unused files; duplicate code; circular deps; complexity hotspots; AI-change audit drift | -The six conformance ESLint rules: `feature-must-have-manifest` (error), `usecase-must-have-test-file` (error), `required-cores-installed` (error), `usecase-must-be-wired` (error), `no-undeclared-event-publish` (warn), `no-undeclared-audit` (warn). Fallow runs as a fifth layer, post-ESLint, whole-codebase. +The seven conformance ESLint rules: `feature-must-have-manifest` (error), `usecase-must-have-test-file` (error), `required-cores-installed` (error), `usecase-must-be-wired` (error), `no-undeclared-event-publish` (warn), `no-undeclared-audit` (warn), `no-undeclared-analytics-event` (warn). Fallow runs as a fifth layer, post-ESLint, whole-codebase. See `docs/architecture/agent-first-workflow-and-conformance.md` for the full design and `docs/guides/conformance-quickref.md` for the day-to-day reference. diff --git a/docs/architecture/template-tiers.md b/docs/architecture/template-tiers.md index 23027a3..103df01 100644 --- a/docs/architecture/template-tiers.md +++ b/docs/architecture/template-tiers.md @@ -15,13 +15,14 @@ Plus all 5 feature packages: auth, blog, marketing-pages, navigation, media. ## Optional (scaffolded on demand) -| Package | Generator | ADR | Guide | -|---|---|---|---| -| core-realtime | `pnpm turbo gen core-package realtime` | ADR-016 | docs/guides/realtime.md | -| core-events | `pnpm turbo gen core-package events` | ADR-015 | docs/guides/events-and-jobs.md | -| core-trpc | `pnpm turbo gen core-package trpc` | (none) | (none) | -| core-ui | `pnpm turbo gen core-package ui` | (none) | (none) | -| core-audit | `pnpm turbo gen core-package audit` | ADR-018 | docs/guides/audit-and-compliance.md | +| Package | Generator | ADR | Guide | +| -------------- | --------------------------------------- | ------- | ----------------------------------- | +| core-realtime | `pnpm turbo gen core-package realtime` | ADR-016 | docs/guides/realtime.md | +| core-events | `pnpm turbo gen core-package events` | ADR-015 | docs/guides/events-and-jobs.md | +| core-trpc | `pnpm turbo gen core-package trpc` | (none) | (none) | +| core-ui | `pnpm turbo gen core-package ui` | (none) | (none) | +| core-audit | `pnpm turbo gen core-package audit` | ADR-018 | docs/guides/audit-and-compliance.md | +| core-analytics | `pnpm turbo gen core-package analytics` | ADR-024 | docs/guides/analytics.md | ## Why optional diff --git a/docs/guides/conformance-quickref.md b/docs/guides/conformance-quickref.md index 5bc4f15..85d142e 100644 --- a/docs/guides/conformance-quickref.md +++ b/docs/guides/conformance-quickref.md @@ -86,14 +86,15 @@ The symbol map declares which container symbol each manifest use-case key resolv ## ESLint rules -| Rule | Severity | What it does | -| ----------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | -| `conformance/feature-must-have-manifest` | error | Use-case files require a sibling manifest | -| `conformance/usecase-must-have-test-file` | error | Every `*.use-case.ts` has a sibling `*.use-case.test.ts` | -| `conformance/required-cores-installed` | error | Manifest's `requiredCores` must exist as `core-` packages in pnpm-workspace.yaml | -| `conformance/no-undeclared-event-publish` | warn | `bus.publish("X")` literal must match the manifest's `publishes` for the use case | -| `conformance/no-undeclared-audit` | warn | `auditLog.record({ type: "X" })` literal must match the manifest's `audits` | -| `conformance/usecase-must-be-wired` | error | Every manifest use case must be bound via `wireUseCase({ name: "" })` in `bind-production.ts` / `bind-dev-seed.ts` | +| Rule | Severity | What it does | +| ------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | +| `conformance/feature-must-have-manifest` | error | Use-case files require a sibling manifest | +| `conformance/usecase-must-have-test-file` | error | Every `*.use-case.ts` has a sibling `*.use-case.test.ts` | +| `conformance/required-cores-installed` | error | Manifest's `requiredCores` must exist as `core-` packages in pnpm-workspace.yaml | +| `conformance/no-undeclared-event-publish` | warn | `bus.publish("X")` literal must match the manifest's `publishes` for the use case | +| `conformance/no-undeclared-audit` | warn | `auditLog.record({ type: "X" })` literal must match the manifest's `audits` | +| `conformance/usecase-must-be-wired` | error | Every manifest use case must be bound via `wireUseCase({ name: "" })` in `bind-production.ts` / `bind-dev-seed.ts` | +| `conformance/no-undeclared-analytics-event` | warn | `analytics.track("X")` literal must match the manifest's `analyticsEvents` for the use case | ## Workflow ordering for new use cases @@ -113,6 +114,7 @@ For the fast path: `pnpm turbo gen feature ` scaffolds steps 1 + 2 in a si - **Feature has use cases but no manifest** → `conformance/feature-must-have-manifest` (error) - **Manifest references `requiredCores: ["X"]` but no `core-X` package exists** → `conformance/required-cores-installed` (error) - **One feature consumes `Y` but no feature publishes `Y`** → `pnpm conformance` orphan check (CI gate) +- **Factory calls `analytics.track("X")` but manifest doesn't declare it in `analyticsEvents`** → `conformance/no-undeclared-analytics-event` (warn); add the event slug to the manifest or remove the call ## Pinning down a drift