docs: clarify configuration guidance

commit: bad4103e6a683871a022653b9622586902c806fb
author: brice · 4mo ago · 2026-05-30 09:07 UTC
parent: 79118a8
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +92 -151

M README.md +67 -13


@@ -4,15 +4,28 @@
4	4
5	5		It is built on `golang.org/x/tools/go/analysis`, runs as a standalone CLI, and can be embedded in a custom `golangci-lint` binary through the Module Plugin System.
6	6
7		-	## Goals
	7	+	## What it checks
8	8
9		-	- map project packages to configurable architecture components
10		-	- catch deterministic boundary violations in CI
11		-	- warn about suspicious business logic in adapters and entrypoints
12		-	- warn when tests bypass generated interface mocks with local fakes or real adapters
13		-	- smoke test the analyzer against real Go repositories through opt-in local paths
	9	+	- dependency direction between configurable architecture roles
	10	+	- framework or infrastructure types leaking into core/port APIs
	11	+	- suspicious business logic in adapters and entrypoints
	12	+	- missing generated mocks for port interfaces
	13	+	- local fakes or concrete adapters in tests where generated mocks should be used
14	14
15		-	## Quick example
	15	+	## Architecture roles
	16	+
	17	+	`hexcheck` does not require folders to be named `domain`, `usecase`, or `adapters`. A repository maps its own paths to roles in `.hexcheck.yaml`.
	18	+
	19	+	Supported roles:
	20	+
	21	+	- `core` — domain/core business logic
	22	+	- `usecase` — application use cases and orchestration
	23	+	- `ports` — interfaces/contracts
	24	+	- `adapter` — infrastructure, persistence, external services, outbound adapters
	25	+	- `entrypoint` — CLI, HTTP handlers, UI entrypoints, app bootstrap
	26	+	- `ignore` — generated code, mocks, vendored paths
	27	+
	28	+	## Quick config
16	29
17	30		```yaml
18	31		version: 1

@@ -21,24 +34,35 @@ components:
21	34		role: core
22	35		paths:
23	36		- internal/domain/**
24		-	usecase:
	37	+	- internal/core/**
	38	+	usecases:
25	39		role: usecase
26	40		paths:
27	41		- internal/application/usecase/**
	42	+	- internal/application/usecases/**
	43	+	- internal/usecase/**
	44	+	- internal/usecases/**
28	45		ports:
29	46		role: ports
30	47		paths:
31	48		- internal/application/port/**
	49	+	- internal/domain/repository/**
32	50		adapters:
33	51		role: adapter
34	52		paths:
35	53		- internal/infrastructure/**
36		-	- internal/ui/**
37		-	- internal/cli/**
	54	+	- internal/adapters/**
38	55		entrypoints:
39	56		role: entrypoint
40	57		paths:
41	58		- cmd/**
	59	+	generated:
	60	+	role: ignore
	61	+	paths:
	62	+	- '/mocks/'
	63	+	- '/generated/'
	64	+	- '*/_templ.go'
	65	+	- '*/_gen.go'
42	66
43	67		rules:
44	68		no-adapter-imports-in-core: error

@@ -48,13 +72,41 @@ rules:
48	72		no-adapter-to-adapter-imports: warn
49	73		suspicious-business-logic-in-adapter: warn
50	74		no-local-fakes-for-ports: warn
	75	+	missing-generated-mock-for-port: warn
51	76		prefer-generated-mocks: warn
	77	+
	78	+	heuristics:
	79	+	businessLogicThreshold: 8
	80	+	businessLogicMinStrongSignals: 2
	81	+	businessLogicMinWeakSignals: 2
	82	+	businessLogicMaxFunctionNodes: 2000
	83	+	businessLogicMaxDiagnosticsPerPackage: 10
	84	+	excludeTestFiles: true
	85	+
	86	+	mocking:
	87	+	generatedMockPaths:
	88	+	- internal/mocks/**
	89	+	- internal/application/mocks/**
	90	+	- internal/application/port/mocks/**
	91	+	generatedMockNamePatterns:
	92	+	- Mock{{Interface}}
	93	+	- '{{Interface}}Mock'
52	94		```
53	95
	96	+	A fuller example lives in [`examples/hexcheck.yaml`](examples/hexcheck.yaml).
	97	+
54	98		## Standalone CLI
55	99
	100	+	Because `hexcheck` is a `go/analysis` analyzer, standalone flags use the analyzer prefix:
	101	+
56	102		```bash
57		-	hexcheck --config .hexcheck.yaml ./...
	103	+	hexcheck -hexcheck.config .hexcheck.yaml -hexcheck.root . ./...
	104	+	```
	105	+
	106	+	During development:
	107	+
	108	+	```bash
	109	+	go run ./cmd/hexcheck -hexcheck.config examples/hexcheck.yaml -hexcheck.root . ./...
58	110		```
59	111
60	112		## golangci-lint module plugin

@@ -68,7 +120,6 @@ golangci-lint custom -c examples/custom-gcl.yml
68	120		Example builder config:
69	121
70	122		```yaml
71		-	# examples/custom-gcl.yml
72	123		version: v2.12.2
73	124		name: hex-golangci-lint
74	125		destination: ./bin

@@ -81,7 +132,6 @@ plugins:
81	132		Enable it in a project:
82	133
83	134		```yaml
84		-	# examples/golangci.yml
85	135		version: "2"
86	136		linters:
87	137		enable:

@@ -95,6 +145,10 @@ linters:
95	145		config: .hexcheck.yaml
96	146		```
97	147
	148	+	## Agent configuration guide
	149	+
	150	+	[`SKILL.md`](SKILL.md) explains how an agent should configure `hexcheck` for a new repository, including non-standard layouts such as `core`/`boundaries`.
	151	+
98	152		## Local development
99	153
100	154		```bash

 It is built on `golang.org/x/tools/go/analysis`, runs as a standalone CLI, and can be embedded in a custom `golangci-lint` binary through the Module Plugin System.
-## Goals
+## What it checks
-- map project packages to configurable architecture components
+- dependency direction between configurable architecture roles
-- catch deterministic boundary violations in CI
+- framework or infrastructure types leaking into core/port APIs
-- warn about suspicious business logic in adapters and entrypoints
+- suspicious business logic in adapters and entrypoints
-- warn when tests bypass generated interface mocks with local fakes or real adapters
+- missing generated mocks for port interfaces
-- smoke test the analyzer against real Go repositories through opt-in local paths
+- local fakes or concrete adapters in tests where generated mocks should be used
-## Quick example
+## Architecture roles
+`hexcheck` does not require folders to be named `domain`, `usecase`, or `adapters`. A repository maps its own paths to roles in `.hexcheck.yaml`.
+Supported roles:
+- `core` — domain/core business logic
+- `usecase` — application use cases and orchestration
+- `ports` — interfaces/contracts
+- `adapter` — infrastructure, persistence, external services, outbound adapters
+- `entrypoint` — CLI, HTTP handlers, UI entrypoints, app bootstrap
+- `ignore` — generated code, mocks, vendored paths
+## Quick config
 ```yaml
 version: 1
     role: core
     paths:
       - internal/domain/**
-  usecase:
+      - internal/core/**
+  usecases:
     role: usecase
     paths:
       - internal/application/usecase/**
+      - internal/application/usecases/**
+      - internal/usecase/**
+      - internal/usecases/**
   ports:
     role: ports
     paths:
       - internal/application/port/**
+      - internal/domain/repository/**
   adapters:
     role: adapter
     paths:
       - internal/infrastructure/**
-      - internal/ui/**
+      - internal/adapters/**
-      - internal/cli/**
   entrypoints:
     role: entrypoint
     paths:
       - cmd/**
+  generated:
+    role: ignore
+    paths:
+      - '**/mocks/**'
+      - '**/generated/**'
+      - '**/*_templ.go'
+      - '**/*_gen.go'
 rules:
   no-adapter-imports-in-core: error
   no-adapter-to-adapter-imports: warn
   suspicious-business-logic-in-adapter: warn
   no-local-fakes-for-ports: warn
+  missing-generated-mock-for-port: warn
   prefer-generated-mocks: warn
+heuristics:
+  businessLogicThreshold: 8
+  businessLogicMinStrongSignals: 2
+  businessLogicMinWeakSignals: 2
+  businessLogicMaxFunctionNodes: 2000
+  businessLogicMaxDiagnosticsPerPackage: 10
+  excludeTestFiles: true
+mocking:
+  generatedMockPaths:
+    - internal/mocks/**
+    - internal/application/mocks/**
+    - internal/application/port/mocks/**
+  generatedMockNamePatterns:
+    - Mock{{Interface}}
+    - '{{Interface}}Mock'
 ```
+A fuller example lives in [`examples/hexcheck.yaml`](examples/hexcheck.yaml).
 ## Standalone CLI
+Because `hexcheck` is a `go/analysis` analyzer, standalone flags use the analyzer prefix:
 ```bash
-hexcheck --config .hexcheck.yaml ./...
+hexcheck -hexcheck.config .hexcheck.yaml -hexcheck.root . ./...
+```
+During development:
+```bash
+go run ./cmd/hexcheck -hexcheck.config examples/hexcheck.yaml -hexcheck.root . ./...
 ```
 ## golangci-lint module plugin
 Example builder config:
 ```yaml
-# examples/custom-gcl.yml
 version: v2.12.2
 name: hex-golangci-lint
 destination: ./bin
 Enable it in a project:
 ```yaml
-# examples/golangci.yml
 version: "2"
 linters:
   enable:
           config: .hexcheck.yaml
 ```
+## Agent configuration guide
+[`SKILL.md`](SKILL.md) explains how an agent should configure `hexcheck` for a new repository, including non-standard layouts such as `core`/`boundaries`.
 ## Local development
 ```bash

M SKILL.md +25 -138

@@ -1,86 +1,36 @@
1	1		---
2	2		name: hexcheck
3		-	description: Use when configuring or running hexcheck in a Go repository to enforce hexagonal architecture boundaries, adapter business-logic warnings, and mock discipline.
	3	+	description: Use when configuring or running hexcheck in a Go repo for hexagonal architecture boundaries, adapter business-logic warnings, and mock discipline.
4	4		---
5	5
6		-	# Hexcheck Configuration Skill
	6	+	# Hexcheck
7	7
8		-	Use `hexcheck` to lint Go repositories for hexagonal / clean architecture violations.
	8	+	Configure `.hexcheck.yaml` by mapping repo paths to roles. Folder names do not matter; roles do.
9	9
10		-	## Core idea
	10	+	Roles:
	11	+	- `core`: domain/core business logic
	12	+	- `usecase`: application use cases/orchestration
	13	+	- `ports`: interfaces/contracts
	14	+	- `adapter`: infra, persistence, external services, outbound adapters
	15	+	- `entrypoint`: CLI/HTTP/UI/bootstrap
	16	+	- `ignore`: generated code, mocks, vendor
11	17
12		-	`hexcheck` does not require folders to have fixed names. It maps project-specific paths to architecture roles through `.hexcheck.yaml`.
13		-
14		-	Supported roles:
15		-
16		-	- `core` — domain entities, value objects, domain services, core business logic
17		-	- `usecase` — application services/use cases/orchestration
18		-	- `ports` — interfaces/contracts that core/usecases depend on
19		-	- `adapter` — infrastructure, persistence, external services, outbound adapters
20		-	- `entrypoint` — CLI, HTTP handlers, UI entrypoints, app bootstrap
21		-	- `ignore` — generated code, mocks, vendored or ignored paths
22		-
23		-	Component names are arbitrary. The `role` is what matters.
24		-
25		-	## Example mappings
26		-
27		-	A repo with `domain`, `application`, and `infrastructure`:
28		-
29		-	```yaml
30		-	components:
31		-	domain:
32		-	role: core
33		-	paths:
34		-	- internal/domain/**
35		-	usecases:
36		-	role: usecase
37		-	paths:
38		-	- internal/application/usecase/**
39		-	- internal/application/usecases/**
40		-	ports:
41		-	role: ports
42		-	paths:
43		-	- internal/application/port/**
44		-	infrastructure:
45		-	role: adapter
46		-	paths:
47		-	- internal/infrastructure/**
48		-	cli:
49		-	role: entrypoint
50		-	paths:
51		-	- cmd/**
52		-	- internal/cli/**
53		-	```
54		-
55		-	A repo that uses `core` and `boundaries`:
	18	+	Minimal shape:
56	19
57	20		```yaml
	21	+	version: 1
58	22		components:
59		-	core:
60		-	role: core
61		-	paths:
62		-	- internal/core/**
63		-	usecases:
64		-	role: usecase
65		-	paths:
66		-	- internal/usecases/**
67		-	inboundBoundaries:
68		-	role: entrypoint
69		-	paths:
70		-	- internal/boundaries/in/**
71		-	outboundBoundaries:
72		-	role: adapter
73		-	paths:
74		-	- internal/boundaries/out/**
75		-	contracts:
76		-	role: ports
77		-	paths:
78		-	- internal/boundaries/ports/**
	23	+	core: { role: core, paths: [internal/domain/, internal/core/] }
	24	+	usecases: { role: usecase, paths: [internal/application/usecase/, internal/application/usecases/, internal/usecases/**] }
	25	+	ports: { role: ports, paths: [internal/application/port/, internal/domain/repository/] }
	26	+	adapters: { role: adapter, paths: [internal/infrastructure/, internal/adapters/] }
	27	+	entrypoints: { role: entrypoint, paths: [cmd/**] }
	28	+	generated: { role: ignore, paths: ['/mocks/', '/generated/', '*/_templ.go', '*/_gen.go'] }
79	29		```
80	30
81		-	## Recommended defaults
	31	+	For repos using `boundaries`, map by role, e.g. `boundaries/in -> entrypoint`, `boundaries/out -> adapter`, `boundaries/ports -> ports`.
82	32
83		-	Start strict on deterministic rules and warning-first on heuristics:
	33	+	Recommended rules:
84	34
85	35		```yaml
86	36		rules:

@@ -95,81 +45,18 @@ rules:
95	45		prefer-generated-mocks: warn
96	46		```
97	47
98		-	## Business-logic heuristic
99		-
100		-	`suspicious-business-logic-in-adapter` is cumulative and package-local. It should not scan the whole repository. It combines strong and weak evidence:
101		-
102		-	- business keywords such as `Validate`, `Migrate`, `Resolve`, `Score`, `Restore`, `Purge`, `Update`
103		-	- policy constants and branching
104		-	- domain/core mutation or method calls
105		-	- multiple port/usecase collaborators when combined with business wording
106		-
107		-	Use `excludePaths` for adapter areas where warnings are not useful:
108		-
109		-	```yaml
110		-	ruleSettings:
111		-	suspicious-business-logic-in-adapter:
112		-	excludePaths:
113		-	- internal/ui/generated/**
114		-	```
115		-
116		-	## Generated code
117		-
118		-	Always ignore generated code and mocks:
119		-
120		-	```yaml
121		-	components:
122		-	generated:
123		-	role: ignore
124		-	paths:
125		-	- '/mocks/'
126		-	- '/generated/'
127		-	- '*/_templ.go'
128		-	- '*/_gen.go'
129		-	```
130		-
131		-	`hexcheck` also ignores files with a standard `// Code generated ... DO NOT EDIT.` comment.
132		-
133		-	## Mock discipline
134		-
135		-	Configure generated mock locations so `hexcheck` can distinguish missing mocks from local fake misuse:
	48	+	Mock config:
136	49
137	50		```yaml
138	51		mocking:
139		-	generatedMockPaths:
140		-	- internal/mocks/**
141		-	- internal/application/mocks/**
142		-	- internal/application/port/mocks/**
143		-	- internal/domain/repository/mocks/**
144		-	generatedMockNamePatterns:
145		-	- Mock{{Interface}}
146		-	- '{{Interface}}Mock'
	52	+	generatedMockPaths: [internal/mocks/, internal/application/mocks/, internal/application/port/mocks/**]
	53	+	generatedMockNamePatterns: ['Mock{{Interface}}', '{{Interface}}Mock']
147	54		```
148	55
149		-	Expected behavior:
150		-
151		-	- `missing-generated-mock-for-port` flags mockable interfaces without generated mocks.
152		-	- `no-local-fakes-for-ports` flags local fakes only when a generated mock exists.
153		-	- Intentional exceptions should use project config `allow` entries or linter suppression comments.
154		-
155		-	## Running
156		-
157		-	Standalone:
	56	+	Run:
158	57
159	58		```bash
160	59		hexcheck -hexcheck.config .hexcheck.yaml -hexcheck.root . ./...
161	60		```
162	61
163		-	With a custom golangci-lint binary, use the module plugin config from `examples/custom-gcl.yml` and `examples/golangci.yml`.
164		-
165		-	## Agent checklist
166		-
167		-	When configuring a new repo:
168		-
169		-	1. Read architecture docs (`AGENTS.md`, `README`, docs) before guessing paths.
170		-	2. Map local folder names to roles; do not force folder renames.
171		-	3. Add generated/mocks ignore paths.
172		-	4. Add mock paths and name patterns.
173		-	5. Run `hexcheck` once and inspect counts by rule.
174		-	6. Tune `ruleSettings.*.excludePaths` for known technical adapters only after reviewing examples.
175		-	7. Keep deterministic rules as `error`; keep heuristic rules as `warn` until signal is proven.
	62	+	Agent checklist: read repo architecture docs, map paths to roles, ignore generated/mocks, configure mock paths, run once, tune `ruleSettings.*.excludePaths` only after inspecting examples.

@@ -1,86 +1,36 @@
1		---	1		---
2		name: hexcheck	2		name: hexcheck
3	-	description: Use when configuring or running hexcheck in a Go repository to enforce hexagonal architecture boundaries, adapter business-logic warnings, and mock discipline.	3	+	description: Use when configuring or running hexcheck in a Go repo for hexagonal architecture boundaries, adapter business-logic warnings, and mock discipline.
4		---	4		---
5			5
6	-	# Hexcheck Configuration Skill	6	+	# Hexcheck
7			7
8	-	Use `hexcheck` to lint Go repositories for hexagonal / clean architecture violations.	8	+	Configure `.hexcheck.yaml` by mapping repo paths to roles. Folder names do not matter; roles do.
9			9
10	-	## Core idea	10	+	Roles:
			11	+	- `core`: domain/core business logic
			12	+	- `usecase`: application use cases/orchestration
			13	+	- `ports`: interfaces/contracts
			14	+	- `adapter`: infra, persistence, external services, outbound adapters
			15	+	- `entrypoint`: CLI/HTTP/UI/bootstrap
			16	+	- `ignore`: generated code, mocks, vendor
11			17
12	-	`hexcheck` does not require folders to have fixed names. It maps project-specific paths to architecture roles through `.hexcheck.yaml`.	18	+	Minimal shape:
13	-
14	-	Supported roles:
15	-
16	-	- `core` — domain entities, value objects, domain services, core business logic
17	-	- `usecase` — application services/use cases/orchestration
18	-	- `ports` — interfaces/contracts that core/usecases depend on
19	-	- `adapter` — infrastructure, persistence, external services, outbound adapters
20	-	- `entrypoint` — CLI, HTTP handlers, UI entrypoints, app bootstrap
21	-	- `ignore` — generated code, mocks, vendored or ignored paths
22	-
23	-	Component names are arbitrary. The `role` is what matters.
24	-
25	-	## Example mappings
26	-
27	-	A repo with `domain`, `application`, and `infrastructure`:
28	-
29	-	```yaml
30	-	components:
31	-	domain:
32	-	role: core
33	-	paths:
34	-	- internal/domain/**
35	-	usecases:
36	-	role: usecase
37	-	paths:
38	-	- internal/application/usecase/**
39	-	- internal/application/usecases/**
40	-	ports:
41	-	role: ports
42	-	paths:
43	-	- internal/application/port/**
44	-	infrastructure:
45	-	role: adapter
46	-	paths:
47	-	- internal/infrastructure/**
48	-	cli:
49	-	role: entrypoint
50	-	paths:
51	-	- cmd/**
52	-	- internal/cli/**
53	-	```
54	-
55	-	A repo that uses `core` and `boundaries`:
56			19
57		```yaml	20		```yaml
			21	+	version: 1
58		components:	22		components:
59	-	core:	23	+	core: { role: core, paths: [internal/domain/, internal/core/] }
60	-	role: core	24	+	usecases: { role: usecase, paths: [internal/application/usecase/, internal/application/usecases/, internal/usecases/**] }
61	-	paths:	25	+	ports: { role: ports, paths: [internal/application/port/, internal/domain/repository/] }
62	-	- internal/core/**	26	+	adapters: { role: adapter, paths: [internal/infrastructure/, internal/adapters/] }
63	-	usecases:	27	+	entrypoints: { role: entrypoint, paths: [cmd/**] }
64	-	role: usecase	28	+	generated: { role: ignore, paths: ['/mocks/', '/generated/', '*/_templ.go', '*/_gen.go'] }
65	-	paths:
66	-	- internal/usecases/**
67	-	inboundBoundaries:
68	-	role: entrypoint
69	-	paths:
70	-	- internal/boundaries/in/**
71	-	outboundBoundaries:
72	-	role: adapter
73	-	paths:
74	-	- internal/boundaries/out/**
75	-	contracts:
76	-	role: ports
77	-	paths:
78	-	- internal/boundaries/ports/**
79		```	29		```
80			30
81	-	## Recommended defaults	31	+	For repos using `boundaries`, map by role, e.g. `boundaries/in -> entrypoint`, `boundaries/out -> adapter`, `boundaries/ports -> ports`.
82			32
83	-	Start strict on deterministic rules and warning-first on heuristics:	33	+	Recommended rules:
84			34
85		```yaml	35		```yaml
86		rules:	36		rules:

@@ -95,81 +45,18 @@ rules:
95		prefer-generated-mocks: warn	45		prefer-generated-mocks: warn
96		```	46		```
97			47
98	-	## Business-logic heuristic	48	+	Mock config:
99	-
100	-	`suspicious-business-logic-in-adapter` is cumulative and package-local. It should not scan the whole repository. It combines strong and weak evidence:
101	-
102	-	- business keywords such as `Validate`, `Migrate`, `Resolve`, `Score`, `Restore`, `Purge`, `Update`
103	-	- policy constants and branching
104	-	- domain/core mutation or method calls
105	-	- multiple port/usecase collaborators when combined with business wording
106	-
107	-	Use `excludePaths` for adapter areas where warnings are not useful:
108	-
109	-	```yaml
110	-	ruleSettings:
111	-	suspicious-business-logic-in-adapter:
112	-	excludePaths:
113	-	- internal/ui/generated/**
114	-	```
115	-
116	-	## Generated code
117	-
118	-	Always ignore generated code and mocks:
119	-
120	-	```yaml
121	-	components:
122	-	generated:
123	-	role: ignore
124	-	paths:
125	-	- '/mocks/'
126	-	- '/generated/'
127	-	- '*/_templ.go'
128	-	- '*/_gen.go'
129	-	```
130	-
131	-	`hexcheck` also ignores files with a standard `// Code generated ... DO NOT EDIT.` comment.
132	-
133	-	## Mock discipline
134	-
135	-	Configure generated mock locations so `hexcheck` can distinguish missing mocks from local fake misuse:
136			49
137		```yaml	50		```yaml
138		mocking:	51		mocking:
139	-	generatedMockPaths:	52	+	generatedMockPaths: [internal/mocks/, internal/application/mocks/, internal/application/port/mocks/**]
140	-	- internal/mocks/**	53	+	generatedMockNamePatterns: ['Mock{{Interface}}', '{{Interface}}Mock']
141	-	- internal/application/mocks/**
142	-	- internal/application/port/mocks/**
143	-	- internal/domain/repository/mocks/**
144	-	generatedMockNamePatterns:
145	-	- Mock{{Interface}}
146	-	- '{{Interface}}Mock'
147		```	54		```
148			55
149	-	Expected behavior:	56	+	Run:
150	-
151	-	- `missing-generated-mock-for-port` flags mockable interfaces without generated mocks.
152	-	- `no-local-fakes-for-ports` flags local fakes only when a generated mock exists.
153	-	- Intentional exceptions should use project config `allow` entries or linter suppression comments.
154	-
155	-	## Running
156	-
157	-	Standalone:
158			57
159		```bash	58		```bash
160		hexcheck -hexcheck.config .hexcheck.yaml -hexcheck.root . ./...	59		hexcheck -hexcheck.config .hexcheck.yaml -hexcheck.root . ./...
161		```	60		```
162			61
163	-	With a custom golangci-lint binary, use the module plugin config from `examples/custom-gcl.yml` and `examples/golangci.yml`.	62	+	Agent checklist: read repo architecture docs, map paths to roles, ignore generated/mocks, configure mock paths, run once, tune `ruleSettings.*.excludePaths` only after inspecting examples.
164	-
165	-	## Agent checklist
166	-
167	-	When configuring a new repo:
168	-
169	-	1. Read architecture docs (`AGENTS.md`, `README`, docs) before guessing paths.
170	-	2. Map local folder names to roles; do not force folder renames.
171	-	3. Add generated/mocks ignore paths.
172	-	4. Add mock paths and name patterns.
173	-	5. Run `hexcheck` once and inspect counts by rule.
174	-	6. Tune `ruleSettings.*.excludePaths` for known technical adapters only after reviewing examples.
175	-	7. Keep deterministic rules as `error`; keep heuristic rules as `warn` until signal is proven.