fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(guides): conformance-quickref includes fallow row + audit usage

Browse Source
This commit is contained in:
Danijel Martinek
2026-05-13 08:52:37 +02:00
parent 1655cd0879
commit d34b841256
1 changed files with 37 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/guides/conformance-quickref.md
View File

@@ -33,7 +33,7 @@ export type FooManifest = typeof fooManifest;
Field reference: Field reference:
| Field | Type | Meaning | | Field | Type | Meaning |
|---|---|---| | --------------------------- | -------------- | --------------------------------------------------------------------------- |
| `name` | string literal | Feature name (kebab-case, matches package name) | | `name` | string literal | Feature name (kebab-case, matches package name) |
| `requiredCores` | string[] | Optional cores this feature requires (e.g. `["audit", "events"]`) | | `requiredCores` | string[] | Optional cores this feature requires (e.g. `["audit", "events"]`) |
| `useCases.<name>.mutates` | boolean | True for create/update/delete; drives whether `__audited` brand is required | | `useCases.<name>.mutates` | boolean | True for create/update/delete; drives whether `__audited` brand is required |
@@ -74,19 +74,20 @@ export function bindProductionFoo(ctx: BindProductionContext): void {
The symbol map declares which container symbol each manifest use-case key resolves to. 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 | | Gate | When it fires | What it catches | Severity |
|---|---|---|---| | ------------------ | --------------------- | ------------------------------------------------------------------------ | -------------------- |
| `tsc` | on save | forgotten wrappers; manifest-derived slot type rejects unwrapped factory | error | | `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 | | `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 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 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 ## ESLint rules
| Rule | Severity | What it does | | Rule | Severity | What it does |
|---|---|---| | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `conformance/feature-must-have-manifest` | error | Use-case files require a sibling manifest | | `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/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-<name>` packages in pnpm-workspace.yaml | | `conformance/required-cores-installed` | error | Manifest's `requiredCores` must exist as `core-<name>` packages in pnpm-workspace.yaml |
@@ -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. 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`. For the deeper design rationale see `docs/architecture/agent-first-workflow-and-conformance.md` and the interactive `feature-conformance-explainer.html`.