From d34b841256e2179d1a311d65b40d989cec3f394b Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Wed, 13 May 2026 08:52:37 +0200 Subject: [PATCH] docs(guides): conformance-quickref includes fallow row + audit usage --- docs/guides/conformance-quickref.md | 61 +++++++++++++++++------------ 1 file changed, 37 insertions(+), 24 deletions(-) diff --git a/docs/guides/conformance-quickref.md b/docs/guides/conformance-quickref.md index 8d6847b..b7783a0 100644 --- a/docs/guides/conformance-quickref.md +++ b/docs/guides/conformance-quickref.md @@ -32,16 +32,16 @@ export type FooManifest = typeof fooManifest; Field reference: -| Field | Type | Meaning | -|---|---|---| -| `name` | string literal | Feature name (kebab-case, matches package name) | -| `requiredCores` | string[] | Optional cores this feature requires (e.g. `["audit", "events"]`) | -| `useCases..mutates` | boolean | True for create/update/delete; drives whether `__audited` brand is required | -| `useCases..audits` | string[] | Audit event types this use case emits via `auditLog.record({ type: "X" })` | -| `useCases..publishes` | string[] | Cross-feature events this use case publishes via `bus.publish("X")` | -| `useCases..consumes` | string[] | Cross-feature events this use case consumes (via an event handler) | -| `realtimeChannels` | string[] | Realtime channels this feature owns | -| `jobs` | string[] | Job slugs this feature enqueues | +| Field | Type | Meaning | +| --------------------------- | -------------- | --------------------------------------------------------------------------- | +| `name` | string literal | Feature name (kebab-case, matches package name) | +| `requiredCores` | string[] | Optional cores this feature requires (e.g. `["audit", "events"]`) | +| `useCases..mutates` | boolean | True for create/update/delete; drives whether `__audited` brand is required | +| `useCases..audits` | string[] | Audit event types this use case emits via `auditLog.record({ type: "X" })` | +| `useCases..publishes` | string[] | Cross-feature events this use case publishes via `bus.publish("X")` | +| `useCases..consumes` | string[] | Cross-feature events this use case consumes (via an event handler) | +| `realtimeChannels` | string[] | Realtime channels this feature owns | +| `jobs` | string[] | Job slugs this feature enqueues | Re-export from `src/index.ts`: @@ -74,24 +74,25 @@ export function bindProductionFoo(ctx: BindProductionContext): void { The symbol map declares which container symbol each manifest use-case key resolves to. -## The four gates +## The five gates -| Gate | When it fires | What it catches | Severity | -|---|---|---|---| -| `tsc` | on save | forgotten wrappers; manifest-derived slot type rejects unwrapped factory | error | -| `eslint` | on save / `pnpm lint` | manifest ↔ code drift; missing sibling test; missing manifest | error or warn | -| `pnpm dev` | at boot | binding lost its runtime brand; manifest declares more than wired | throws synchronously | -| `pnpm conformance` | CI | orphan event consumers across features | exits non-zero | +| Gate | When it fires | What it catches | Severity | +| ------------------ | --------------------- | ------------------------------------------------------------------------ | -------------------- | +| `tsc` | on save | forgotten wrappers; manifest-derived slot type rejects unwrapped factory | error | +| `eslint` | on save / `pnpm lint` | manifest ↔ code drift; missing sibling test; missing manifest | error or warn | +| `pnpm dev` | at boot | binding lost its runtime brand; manifest declares more than wired | throws synchronously | +| `pnpm conformance` | CI | orphan event consumers across features | exits non-zero | +| `pnpm fallow` | ~30–60s | unused exports/files, dupes, circular deps, complexity, AI-change audit | warn (currently) | ## 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` | +| 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` | ## Workflow ordering for new use cases @@ -119,6 +120,18 @@ When a gate fires, the error message tells you what to run. For example: That's the "fix" line — follow it. +## Fallow audit for AI changes + +When you (the agent) finish a task and are about to commit, run: + +``` +pnpm fallow:audit +``` + +This runs `fallow audit --base main`, comparing your branch's diff against main. If your change adds dead exports, dupes, or complexity hotspots, fallow tells you exactly what and where. Fix or accept (with --gate flag to ignore inherited findings). + +This is the catch-all for whole-codebase drift the per-file gates can't see. + --- For the deeper design rationale see `docs/architecture/agent-first-workflow-and-conformance.md` and the interactive `feature-conformance-explainer.html`.