Skip to content

Commit e0ab584

Browse files
committed
docs: P-023 architecture guard proposal (Own.Arch)
Intent model (architecture.rules.yaml) vs actual dependency graph, with a baseline ratchet: only new violations fail the build. Fingerprint policy, CI decision table, SARIF/markdown reporting, tiered ARCH### diagnostics (deterministic / heuristic / report-only), explicit non-goals (no C4 as source of truth, no runtime telemetry, no dead-code gates). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JvV8eSjV4R1Qi1vGw6fDg2
1 parent 3a18de7 commit e0ab584

2 files changed

Lines changed: 310 additions & 0 deletions

File tree

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
# P-023 — Architecture guard (`Own.Arch`)
2+
3+
- **Status:** draft — design accepted in discussion; implementation not started.
4+
- **Depends on:** [P-013](P-013-distribution-surface.md) (CI Action / dotnet tool
5+
surface — the guard rides the same delivery rails) and
6+
[P-015](P-015-configuration-surface.md) (severity policy vocabulary). Phase 2
7+
reuses the Roslyn extraction stack from
8+
[P-001](P-001-csharp-extractor.md). Reporting reuses the SARIF export design
9+
from [`docs/notes/sarif-export.md`](../notes/sarif-export.md).
10+
11+
## Motivation
12+
13+
Architecture drift is the gap between the intended dependency structure of a
14+
codebase and what the code actually does. In a living solution it accumulates
15+
one "temporary" reference at a time: a ViewModel reaches into a SQL repository,
16+
a Domain project quietly picks up a DevExpress package, and six months later the
17+
layer diagram is fiction.
18+
19+
Every attempt to fix this with a "detect everything bad" platform dies the same
20+
way:
21+
22+
```text
23+
turn on the rules
24+
get 800 violations on day one
25+
downgrade everything to warnings
26+
nobody reads warnings
27+
initiative dead in a month
28+
```
29+
30+
Own.Arch deliberately does **not** build a SOLID detector, a documentation-sync
31+
checker, or a runtime-telemetry differ. The value proposition is one sentence:
32+
33+
> **Own.Arch fails a PR if and only if it introduces a *new* architectural
34+
> dependency violation. Existing debt is baselined, ratcheted, and reported —
35+
> never a build blocker.**
36+
37+
Three artefacts, one direction of truth:
38+
39+
```text
40+
intent model: architecture.rules.yaml (hand-written, reviewed)
41+
actual model: dependency graph extracted from .sln/.csproj/assemblies
42+
drift: actual − allowed → verdicts, gated against a baseline
43+
```
44+
45+
Diagrams, reports, and tests are all *generated from* the intent model. There is
46+
no second place where the intended architecture lives — no hand-maintained C4
47+
model competing with the rules for source-of-truth status.
48+
49+
## Scope
50+
51+
### MVP: project-level dependency guard
52+
53+
The MVP reads the solution's project graph — no compilation, no Roslyn — and
54+
gates on it:
55+
56+
| Code | Finding | Default severity | Confidence |
57+
|------|---------|------------------|------------|
58+
| `ARCH001` | `ProjectReference` from layer X to layer Y not in the allowed graph | error (if not baselined) | deterministic — it is an edge in a graph |
59+
| `ARCH002` | Forbidden `PackageReference` / `packages.config` entry in a layer (e.g. SQL provider in Domain) | error (if not baselined) | deterministic for direct references |
60+
| `ARCH003` | Project matches no layer pattern, or matches more than one | error, never baselinable | configuration defect — default deny |
61+
| `ARCH030` | Allowed edge that no project actually uses (reverse drift: the intent model is rotting) | info / report only | deterministic |
62+
63+
`ARCH003` is the discipline rule: an unmapped project is a hole in the guard,
64+
so the mapping is forced to stay total and unambiguous. The cheapest bypass —
65+
name the project `Broker.Utils` and reference whatever you like — must not
66+
exist.
67+
68+
`ARCH030` is what distinguishes a guard from yet another linter: the intent
69+
model decays too, and "declared but unused dependency" is the only automatic
70+
signal of that decay.
71+
72+
### Phase 2: type-level facts
73+
74+
After the project-level guard has survived contact with a real solution:
75+
76+
| Code | Finding | Default severity | Confidence |
77+
|------|---------|------------------|------------|
78+
| `ARCH010` | Type in layer X depends on a type in layer Y outside the allowed graph (catches violations invisible at project granularity) | error (if not baselined) | deterministic on compiled IL / semantic model |
79+
| `ARCH011` | Forbidden API used in a layer (`System.Windows.MessageBox` in Domain, `SqlConnection` in Application, …) | error (if not baselined) | deterministic |
80+
| `ARCH012` | Namespace-level dependency cycle | warning at first, error once trusted | deterministic |
81+
82+
Note: there is deliberately no *project*-level cycle rule — MSBuild already
83+
refuses to build circular `ProjectReference` graphs. Cycle detection only means
84+
something at namespace/type granularity, which is why it lives in phase 2.
85+
86+
### Phase 3: heuristic signals (never build blockers at introduction)
87+
88+
| Code | Finding | Default severity | Confidence |
89+
|------|---------|------------------|------------|
90+
| `ARCH020` | Type has too many distinct dependencies (fan-out / god-class signal) | warning | heuristic |
91+
| `ARCH021` | Type in layer X mixes APIs from layers Y and Z (SRP *symptom*, not SRP verdict) | warning | heuristic |
92+
| `ARCH022` | Interface with too many members (ISP symptom) | warning | heuristic |
93+
| `ARCH040` | Duplicated code blocks / dead public API | report only | noisy — see Non-goals |
94+
95+
The tiering is the honest answer to "can you detect SOLID?": no. You can
96+
detect **dependency facts** (deterministic — tier 1), **structural symptoms**
97+
(heuristic — tier 2), and **quality smells** (noisy — tier 3). Selling tier 3
98+
as tier 1 is how analyzers lose trust. Dead-code detection in particular, in a
99+
.NET codebase with reflection, DI containers, serialization, and XAML bindings,
100+
false-positives constantly; failing a build on it is out of the question.
101+
102+
## Non-goals
103+
104+
- **No C4 model as source of truth.** C4/PlantUML/Mermaid diagrams are a
105+
*rendering* of `architecture.rules.yaml`, generated in CI, never
106+
hand-edited, never diffed as images. A hand-maintained architecture model
107+
plus separate rules is two parrots arguing about who is the architect.
108+
- **No runtime telemetry diffing** (OpenTelemetry traces vs. declared
109+
architecture). Valuable someday; a separate infrastructure project; not here.
110+
- **No dead-code or clone-detection quality gates.** Report-only, forever, or
111+
until someone proves the false-positive rate on *our* corpus is near zero.
112+
- **No test-coverage or documentation-freshness "drift" checks.** Those are
113+
quality gates, not architecture; bundling them is how the scope eats the
114+
tool.
115+
- **No second rule DSL.** No generated ArchUnitNET/NetArchTest test code. One
116+
intent model (`rules.yaml`), one evaluator that reads it directly. If
117+
type-level extraction needs a library (Cecil, Roslyn), it is used as an
118+
*extractor*, not as a rule language.
119+
- **No hard dependency on commercial tooling** (NDepend et al.). Optional
120+
later evaluation at most.
121+
- **No "SOLID detector" claim.** The rules are SOLID-*inspired*; the README
122+
should say "dependency and layering guard", nothing grander.
123+
124+
## Sketch
125+
126+
The seam is the same deep-module interface as the rest of Own.NET:
127+
128+
```text
129+
.sln/.csproj/packages.config --[extractor]--> arch-facts.json
130+
|
131+
architecture.rules.yaml ----------------------\ |
132+
architecture-baseline.json ---------------------+---+--[core]--> ARCH### verdicts
133+
--> SARIF + markdown report
134+
--> (later) Mermaid/C4 diagrams
135+
```
136+
137+
The extractor emits facts; the core owns verdicts — the "one checker" rule
138+
holds. MVP facts are plain XML reads of project files; phase 2 adds an IL or
139+
Roslyn pass emitting type-dependency facts in the same JSON envelope.
140+
141+
### `architecture.rules.yaml` (intent model)
142+
143+
```yaml
144+
layers:
145+
Presentation:
146+
matches: ["*.Presentation", "*.Wpf", "*.Client"]
147+
Application:
148+
matches: ["*.Application", "*.Services"]
149+
Domain:
150+
matches: ["*.Domain", "*.Core"]
151+
DomainAbstractions:
152+
matches: ["*.Domain.Abstractions"]
153+
Infrastructure:
154+
matches: ["*.Infrastructure", "*.DataAccess"]
155+
156+
# Direct edges only. No transitive closure is implied:
157+
# Presentation -> Application -> Domain does NOT allow Presentation -> Domain.
158+
allowedDependencies:
159+
Presentation: [Application, DomainAbstractions]
160+
Application: [Domain, DomainAbstractions]
161+
Infrastructure: [Domain, DomainAbstractions]
162+
Domain: [DomainAbstractions]
163+
164+
forbiddenPackages:
165+
Domain: [System.Data.SqlClient, Microsoft.Data.SqlClient, DevExpress*, Newtonsoft.Json]
166+
Application: [DevExpress*, PresentationFramework]
167+
168+
# Phase 2:
169+
forbiddenApis:
170+
Domain: [System.Windows.*, System.Data.*]
171+
Application: [System.Windows.MessageBox]
172+
```
173+
174+
Resolution rules, fixed up front:
175+
176+
- A project matching zero or ≥2 layer patterns is `ARCH003` — config error,
177+
cannot be baselined or suppressed.
178+
- Package checks cover **direct** references only in the MVP.
179+
`packages.config` is flat, so legacy solutions get full coverage for free;
180+
SDK-style transitive dependencies need `project.assets.json` parsing and are
181+
explicitly deferred (recorded limitation, not silent gap).
182+
183+
### `architecture-baseline.json` (the ratchet)
184+
185+
Existing violations are frozen at adoption time; the gate only fires on *new*
186+
ones. This is the load-bearing element — without it the guard is architectural
187+
theatre.
188+
189+
```json
190+
{
191+
"rulesHash": "sha256:…of architecture.rules.yaml…",
192+
"violations": [
193+
{
194+
"rule": "ARCH001",
195+
"from": "Broker.Domain",
196+
"to": "Broker.Infrastructure",
197+
"fingerprint": "sha256:ab12…",
198+
"firstSeen": "2026-07-03",
199+
"reason": "legacy tax calculator; tracked as TECH-482"
200+
}
201+
]
202+
}
203+
```
204+
205+
**Fingerprint policy (the make-or-break detail):**
206+
207+
- `fingerprint = sha256(rule ‖ normalized-from-symbol ‖ normalized-to-symbol)`.
208+
**No file paths, no line numbers** — a positional fingerprint churns the
209+
baseline on every refactor; a looser one lets new violations impersonate old
210+
ones.
211+
- Consequence, accepted deliberately: renaming a symbol makes the old entry
212+
"fixed" and the new one "new" → FAIL. That is correct behaviour — it forces
213+
a conscious baseline update in the same PR — but only tolerable if updating
214+
is one command:
215+
216+
```text
217+
own-arch baseline accept --reason "rename only, no new edge"
218+
```
219+
220+
A mandatory `--reason` is the whole suppression policy; entries without one
221+
are rejected.
222+
- The file is **canonically sorted, one violation per line**, so concurrent
223+
PRs merge without conflicts.
224+
- `rulesHash` pins the baseline to the rules version. Tightening a rule
225+
invalidates the baseline; the same PR that changes the rules regenerates it.
226+
A stale hash is a build error, not a silent re-interpretation.
227+
228+
**CI decision table:**
229+
230+
| Observation | Verdict |
231+
|---|---|
232+
| known violation still present | OK (counted, reported) |
233+
| known violation gone | GOOD — entry removed (or PR comment nudges removal) |
234+
| new violation | **FAIL** |
235+
| baseline entry count grew without `--reason` entries | **FAIL** (fallback invariant; normally subsumed by "new → FAIL") |
236+
| `rulesHash` mismatch | **FAIL** — regenerate baseline alongside the rules change |
237+
238+
There is no separate "violation changed → REVIEW" state: with symbol-pair
239+
fingerprints, "changed" decomposes into "one gone + one new", and the policy
240+
above already covers both halves.
241+
242+
### Reporter
243+
244+
- **SARIF** as the primary machine output — GitHub code scanning and Azure
245+
DevOps render it as inline PR annotations for free
246+
(see [`sarif-export.md`](../notes/sarif-export.md); same format, same
247+
rails).
248+
- **Markdown summary** for the PR conversation: new violations first, then the
249+
ratchet status (`baseline: 47 known, −2 this PR`), then `ARCH030` reverse
250+
drift.
251+
- Violation messages name both endpoints and the rule, and suggest the
252+
layer-correct alternative:
253+
254+
```text
255+
ARCH001: Broker.Presentation.DeclarationViewModel → Broker.Infrastructure.SqlCustomerRepository
256+
Presentation may depend on: Application, Domain.Abstractions.
257+
Fix: call an Application service or a Domain abstraction instead.
258+
```
259+
260+
- **Later:** generate Mermaid/PlantUML (optionally via C4 tooling as a pure
261+
renderer) from `rules.yaml`, and overlay the *actual* graph with drift edges
262+
highlighted. The intended diagram and the drift diagram come from the same
263+
two inputs the gate already has — no third model.
264+
265+
## Implementation order
266+
267+
Weeks are calendar-honest, not research-project-honest:
268+
269+
1. **Week 1 — the ratchet works end to end.** `rules.yaml` schema + parser;
270+
`.sln`/`.csproj`/`packages.config` extractor; `ARCH001`–`ARCH003`
271+
evaluation; baseline generate/accept/check; CI wiring.
272+
**Exit criterion: on a real solution, the baseline is frozen and a
273+
deliberately broken PR goes red.** A green pipeline proves nothing; the red
274+
PR is the acceptance test.
275+
2. **Week 2 — feedback quality.** SARIF + markdown reporter; `--reason`
276+
suppression flow; `ARCH030` reverse drift; docs for "my PR went red, what
277+
now".
278+
3. **Week 3 — type-level facts.** IL/Roslyn dependency extraction feeding
279+
`ARCH010`–`ARCH012`; forbidden-API list; same baseline mechanics (the
280+
fingerprint scheme already accommodates type-granularity symbols).
281+
4. **Later, separately justified:** phase-3 heuristics as warnings; diagram
282+
generation; transitive package closure via `project.assets.json`;
283+
multi-solution/monorepo layout support.
284+
285+
## Open questions
286+
287+
1. **Where does the evaluator live?** The one-checker rule says the Python core
288+
owns verdicts (extractor emits `arch-facts.json`, core evaluates). But
289+
unlike ownership analysis, this checker is a graph-set difference — trivial
290+
in either language — and a self-contained dotnet tool is easier to adopt in
291+
C#-only shops. Leaning: follow the house seam (facts → Python core) for
292+
consistency and shared reporting, but keep the fact schema tool-agnostic so
293+
a standalone runner remains possible.
294+
2. **Phase-2 extraction: Mono.Cecil over compiled assemblies, or Roslyn over
295+
source?** Cecil sees what actually ships (including generated code) but
296+
needs a build first; Roslyn integrates with the P-001 stack and sees
297+
pre-build. Leaning: Cecil for dependency edges (cheap, whole-assembly),
298+
Roslyn only if forbidden-API checks need syntax-level precision.
299+
3. **Does `rules.yaml` fold into the P-015 configuration surface,** or stay a
300+
separate file? Leaning: separate file — it is a reviewed architectural
301+
artefact with its own change ceremony, not a per-developer knob.
302+
4. **Fingerprint stability at type granularity:** namespace-qualified type
303+
pairs churn more than project pairs under refactoring. Is `(rule, from-type,
304+
to-type)` right, or should type-level entries baseline at
305+
`(rule, from-namespace, to-namespace)` to reduce accept-noise? Needs a trial
306+
run on a real diff history.
307+
5. **Naming/positioning:** `Own.Arch` as a product family next to `Own.Async` /
308+
`Own.React`, or a subcommand of the existing CLI? Affects P-013 packaging
309+
only; the seam is unchanged either way.

‎docs/proposals/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ proposal is marked `done` with a pointer.
4242
| [P-020](P-020-ownts-react-effects.md) | OwnTS React effects profile (`Own.React`) — the effect-storm angle | draft |
4343
| [P-021](P-021-async-audit-pack.md) | Async audit pack (`Own.Async`) | draft |
4444
| [P-022](P-022-rust-core-migration.md) | Rust core migration: crate DAG, patterns, prior art, differential oracle (Python = golden) | draft / exploratory |
45+
| [P-023](P-023-architecture-guard.md) | Architecture guard (`Own.Arch`): rules.yaml intent model + dependency-graph gate + baseline ratchet | draft |
4546

4647
> For priorities, milestones, the framing, and the design philosophy across all
4748
> of these, see the strategy hub: [`docs/ROADMAP.md`](../ROADMAP.md). P-004 … P-016

0 commit comments

Comments
 (0)