@opengroundplan/core 0.1.1

package/registry/skills/adr-write/references/adr-template.md

@@ -0,0 +1,143 @@
+# ADR template (MADR style)
+
+Copy into `docs/adr/NNNN-kebab-title.md`. Keep it under two screens. If it runs longer, the decision is probably two decisions.
+
+---
+
+```markdown
+# NNNN — <Decision stated as a decision, not a topic>
+
+- **Status:** proposed
+- **Date:** <YYYY-MM-DD>
+- **Deciders:** <who accepts the consequences>
+- **Supersedes:** <[MMMM](MMMM-old-title.md) or "none">
+- **Superseded by:** <filled in only when this is replaced>
+- **Affects:** <boundaries[] / conventions[] entries this changes, or "none">
+
+## Context and problem
+
+<3-6 sentences. The forces in tension and the constraint that makes this hard.
+State it so the decision looks difficult — if it reads obvious, the real pressure
+is missing. Include what is true *today* that was not true before.>
+
+Constraints in play:
+- <technical constraint>
+- <organizational or cost constraint>
+- <constraint imposed by an earlier ADR, cited by number>
+
+## Decision drivers
+
+- <the criterion that mattered most>
+- <the criterion that killed the runner-up>
+- <a criterion deliberately weighted low, and why>
+
+## Considered options
+
+1. **<Option A>** — <one line>
+2. **<Option B>** — <one line>
+3. **Do nothing / keep the status quo** — <one line; include this unless it is genuinely impossible>
+
+## Decision
+
+We <verb> <option>, because <the single strongest reason>.
+
+<One paragraph maximum of elaboration. Present tense, active voice. Not "it was decided that".>
+
+## Consequences
+
+### Good
+
+- <what gets easier, cheaper, safer, faster>
+- <a future option this keeps open>
+
+### Bad
+
+- <what gets harder or slower — there is always something>
+- <what this forecloses>
+- <the ongoing cost: operational burden, licence, expertise needed>
+- <the condition under which this becomes the wrong choice>
+
+<An ADR with no bad consequences is not finished. Reviewers stop trusting the archive
+the moment they read an all-upside record.>
+
+### Neutral
+
+- <changes that are neither, but that someone will notice>
+
+## Options in detail
+
+Only for options a reader might reasonably still argue for.
+
+### <Option B> — rejected
+
+- **Pros:** <...>
+- **Cons:** <...>
+- **Why rejected:** <the specific disqualifier, not "it was worse">
+- **Would reconsider if:** <the condition that flips this>
+
+## Confirmation
+
+How anyone verifies the decision is actually being followed:
+
+- <a `boundaries[]` line added to AGENTS.md>
+- <a lint/architecture rule>
+- <a test that fails if the decision is violated>
+- <a review checklist item, if nothing automatable exists — say so honestly>
+
+## Follow-ups
+
+- [ ] <migration, cleanup, or deprecation this creates>
+- [ ] Update `AGENTS.md` index line
+- [ ] Update `boundaries[]` / `conventions[]` if this changed either
+
+## References
+
+- <spec that produced this: `specs/NNN-slug/plan.md`>
+- <related ADRs by number>
+- <external source, if a claim rests on it>
+```
+
+---
+
+## AGENTS.md index line
+
+One line per ADR in the recency window. Not the whole archive.
+
+```markdown
+## Decisions (recent)
+
+| # | Decision | Status | Date |
+|---|---|---|---|
+| [0011](docs/adr/0011-....md) | We use an append-only event log for audit trails | accepted | 2026-06-02 |
+| [0012](docs/adr/0012-....md) | We keep the API surface versioned by path, not header | accepted | 2026-06-20 |
+| [0014](docs/adr/0014-....md) | We run migrations forward-only, no down scripts | accepted | 2026-07-09 |
+
+Full archive: `docs/adr/`. Older and superseded records stay on disk and are linked
+from whatever replaced them.
+```
+
+Rules for the index:
+- 3-5 rows. When a sixth accepted ADR lands, the oldest drops out.
+- The "Decision" column is the decision sentence from the ADR, verbatim. Not the title.
+- Superseded and rejected records never appear here.
+- If an entry describes something that must hold for *every* change, promote it into `conventions[]` or `boundaries[]` and let the ADR keep only the rationale.
+
+## Supersede edit
+
+In the old file, change only these lines:
+
+```markdown
+- **Status:** superseded
+- **Superseded by:** [0021](0021-new-title.md) on 2026-07-18
+```
+
+Leave the body untouched — including claims that turned out wrong. The wrongness is the lesson.
+
+## Title patterns
+
+| Weak | Strong |
+|---|---|
+| `0004-database.md` | `0004-use-a-single-primary-datastore-per-module.md` |
+| `0009-caching-strategy.md` | `0009-cache-read-models-only-never-write-paths.md` |
+| `0012-auth.md` | `0012-authorize-at-the-service-boundary-not-in-handlers.md` |
+| `0015-frontend-decisions.md` | split into two ADRs |

package/registry/skills/adr-write/references/when-to-write-an-adr.md

@@ -0,0 +1,74 @@
+# When to write an ADR
+
+The archive is only useful if it is small and every entry earned its place. Over-recording is as damaging as under-recording: thirty ADRs nobody reads is the same as none, plus maintenance.
+
+## The two-question test
+
+Write an ADR if **either** answer is yes:
+
+1. **Is reversal expensive?** Migration, data rewrite, retraining, contract break, vendor lock, or more than a few days of work.
+2. **Is the reasoning non-obvious?** Would a competent engineer arriving later assume it was a mistake, or "fix" it back?
+
+Both no → no ADR. One yes → ADR.
+
+The second question is the one people skip. A cheap-to-reverse decision made for a subtle reason still deserves a record — otherwise someone reverses it, hits the same wall, and reverses back.
+
+## Worked examples
+
+| Situation | ADR? | Why |
+|---|---|---|
+| Chose Postgres over the document store the team knows better | **Yes** | Expensive reversal, and the choice looks wrong without the reason |
+| Chose tabs over spaces | No | `conventions[]` in AGENTS.md; zero reversal cost |
+| Split the monolith's billing module behind a published surface | **Yes** | Changes a declared boundary |
+| Named the service `ledger` instead of `accounting` | No | Naming; a convention at most |
+| Retry with jitter instead of fixed backoff after an incident | **Yes** | Non-obvious; someone will "simplify" it back |
+| Used a specific library version to dodge a known upstream bug | No | Code comment plus a lockfile note — unless the pin blocks an upgrade path, then yes |
+| Made all IDs opaque strings rather than integers | **Yes** | Data shape others build on; expensive to change later |
+| Extracted a helper function | No | Not a decision, an edit |
+| Decided *not* to adopt a much-discussed framework | **Yes** | Rejected ADRs stop the discussion recurring every quarter |
+| Chose forward-only migrations, no down scripts | **Yes** | Operational consequence that surprises new joiners |
+| Set a request timeout value | No | Config with a typed default; the *policy* of how timeouts are chosen might be an ADR |
+| Put authorization at the service boundary rather than in handlers | **Yes** | Security-relevant, and every new handler depends on knowing it |
+| Picked a CSS approach for the app | **Yes** if it constrains every component; no if it is one page |
+
+## Where it goes if it is not an ADR
+
+| Kind of knowledge | Home |
+|---|---|
+| Why this line of code is weird | Code comment, one line |
+| A rule every change must follow | `AGENTS.md` `conventions[]` |
+| A dependency direction that must hold | `AGENTS.md` `boundaries[]` |
+| A choice scoped to one feature, dead when it ships | `specs/NNN-slug/plan.md` |
+| A day-to-day call made mid-task | `.agent/DECISIONS.md` |
+| A tunable value | The config layer, with one typed default |
+| Setup instructions | `AGENTS.md` overview / README |
+
+`.agent/DECISIONS.md` versus ADR: DECISIONS is the working log — append-only, low ceremony, "we went with the second approach because the first deadlocked". When an entry there turns out to constrain future work, *promote* it to an ADR and leave a pointer. Most entries never get promoted, and that is correct.
+
+## Timing
+
+**Write it when the decision is made, not after it ships.** A `proposed` ADR is a cheap way to have the argument once, in writing, before the code exists. Writing it afterwards produces a justification rather than a decision record — the alternatives section becomes fiction because nobody genuinely weighed them.
+
+Backfilling is still worth doing for load-bearing decisions nobody recorded, but mark the reconstructed parts as reconstructed and get them confirmed before setting `accepted`.
+
+## Signs the archive is unhealthy
+
+| Symptom | What it means | Fix |
+|---|---|---|
+| Every ADR has one considered option | They are announcements, not decisions | Require a real rejected alternative, including "do nothing" |
+| No ADR lists a bad consequence | Nobody is being honest | Reject at review; every choice costs something |
+| ADRs get edited after acceptance | The history is being overwritten | Immutable after accept; supersede instead |
+| 30 entries, all "accepted" | Nothing was ever superseded — unlikely | Audit; several are probably dead |
+| The `AGENTS.md` index lists everything | Context burn with no behavior change | Prune to the last 3-5 accepted |
+| Nobody can find the ADR for a known decision | Titles describe topics, not decisions | Rename to decision sentences |
+| The same question is asked in review repeatedly | The decision belongs in `conventions[]`/`boundaries[]` where it is enforced | Promote it; keep the ADR as rationale |
+
+## Why the recency window matters
+
+Agents read `AGENTS.md` on every task. The value of an ADR index there is telling the agent *how this system currently works* — and the last few accepted decisions do that. A full history does not: it mixes current constraints with archaeology, and the agent cannot tell which lines still bind.
+
+Keep 3-5. Everything older stays on disk, stays linked from whatever superseded it, and gets loaded only when someone asks "why not X?". That question is rare; the cost of answering it on demand is far lower than the cost of carrying thirty entries into every request.
+
+## Rejected ADRs are worth more than they look
+
+A well-written rejected ADR ends a recurring argument. It says: we looked, here is what we found, here is what would have to change for the answer to flip. That last clause — **"would reconsider if"** — is what makes it useful two years later, when one of those conditions actually changes and someone can point at the record instead of relitigating from zero.

package/registry/skills/adr-write/skill.yaml

@@ -0,0 +1,7 @@
+id: adr-write
+kind: skill
+name: ADR Author
+description: Write a MADR-style Architecture Decision Record at docs/adr/NNNN-title.md, keep the index in AGENTS.md, and supersede cleanly.
+tags: [architecture, decisions, documentation, adr]
+targets: [claude-code, cursor, github-copilot, windsurf, cline, codex, gemini-cli, agents-md]
+requiresCapability: [instructions]

package/registry/skills/architecture-guard/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: architecture-guard
+description: "Check a change against the repo's declared architecture boundaries. Use when the user says architecture check, boundary violation, does this break the layering, is this import allowed, review the structure, /review, or when a diff adds an import that crosses modules. NOT for style, naming, or performance review."
+metadata:
+  version: 1.0.0
+  category: architecture
+  updated: 2026-07-18
+---
+
+# Architecture Guard
+
+You are an expert at reading a dependency graph and telling whether a change respects the architecture the team actually declared. Your goal is a short, specific report: which rule, which line, which direction, how to fix.
+
+You do not invent architecture. **The boundaries live in the repo, never in this skill.**
+
+## Before Starting
+
+Read the declared boundaries first. Precedence, highest first:
+
+1. `AGENTS.md` → the `boundaries[]` entries from the agent-kit. This is the source of truth.
+2. A machine-enforced config if one exists (dependency-cruiser, ESLint import rules, ArchUnit, `.editorconfig`-style module maps, language-native module visibility).
+3. Directory shape as *evidence* — never as authority. A folder named `domain/` implies intent; it does not declare a rule.
+
+If `boundaries[]` is empty or absent, **stop and say so**. Report the inferred shape and propose boundary lines for `AGENTS.md`, then ask for approval. Guessing a rule and then enforcing it is worse than having no guard — you will block correct work with an invented rule.
+
+Also read `protectedPaths[]`. A change touching one is an automatic STOP regardless of direction.
+
+## How This Skill Works
+
+**Mode 1 — Guard a diff.** Default. Given a change, check only what the change introduces. Pre-existing violations are noted separately, never mixed into the verdict.
+
+**Mode 2 — Audit the repo.** Full sweep against declared boundaries. Produces a violation inventory ranked by blast radius. Expect pre-existing debt; classify it, do not fix it.
+
+**Mode 3 — Propose boundaries.** No `boundaries[]` declared. Infer the intended shape from the directory layout and existing import patterns, propose the rule list, and hand it to the user for `AGENTS.md`.
+
+## Reading a declared boundary
+
+`boundaries[]` entries are prose lines. Normalize each into a triple before checking:
+
+| Field | From the line | Example |
+|---|---|---|
+| source | who may import | `api/` |
+| target | what it may/may not import | `infrastructure/` |
+| direction | allowed, forbidden, or one-way | forbidden |
+
+Common phrasings and what they mean:
+
+- "X must not import Y" → forbidden edge, both files, any depth.
+- "X depends only on Y" → allow-list; every edge out of X that is not Y is a violation.
+- "Y is the only place that talks to the database" → all persistence edges converge on Y; anything else reaching a driver/client is a violation.
+- "features must not import each other" → sibling isolation; edges between peers under the same parent are violations, edges to shared/ are not.
+- "domain has no framework imports" → target is a *category* (the framework's packages), not a folder.
+
+If a line is ambiguous, say which of these you applied and flag the ambiguity — do not pick silently.
+
+## Detecting a violating edge
+
+For each added or modified file in the change:
+
+1. **List its outgoing edges** — imports, requires, `using`, DI registrations, generated-client references, and dynamic/lazy imports. Dynamic imports evade grep for static imports; check both.
+2. **Locate both ends** — map file path → declared zone. A file in no declared zone is unclassified; report it rather than assuming it is fine.
+3. **Compare against the triple** — is this edge forbidden, or outside an allow-list?
+4. **Check direction, not just presence.** `domain → infrastructure` may be forbidden while `infrastructure → domain` is the whole point. Direction is the entire signal.
+5. **Check the transitive hop.** `domain → utils → database-client` violates "domain has no persistence imports" even though `domain` never names the client. A barrel/index re-export is the usual hiding place.
+6. **Check inverted-dependency compliance** — if the rule says the inner layer owns the interface, an inner-layer file importing a concrete outer type is a violation even when the folder names look right.
+
+See [references/boundary-patterns.md](references/boundary-patterns.md) for the per-style rule set — layered, clean, hexagonal, vertical-slice, modular-monolith, and FSD — including which edges each style legitimately allows.
+
+## Violation vs smell
+
+Keep these separate. Mixing them destroys the report's credibility.
+
+| | Violation | Smell |
+|---|---|---|
+| Basis | A declared rule is broken | No declared rule broken |
+| Example | `domain/` imports the HTTP client, and `boundaries[]` forbids it | A shared `utils/` module that everything imports |
+| Verdict impact | FAIL | Never fails the check |
+| Action | Block; name the rule and the line | Note it; suggest a boundary line for `AGENTS.md` |
+
+Rules of thumb:
+- No declared rule → it cannot be a violation. It can still be a smell worth reporting.
+- Pre-existing violation the diff did not touch → note under **pre-existing**, do not fail the change.
+- Pre-existing violation the diff *extends* (one more file joins the pattern) → that is a violation. Adding to debt is a change.
+- Test files may have relaxed rules — but only if `boundaries[]` says so. Do not grant the exemption yourself.
+
+[references/violation-catalog.md](references/violation-catalog.md) has the named failure modes, their signatures, and the fix that usually applies.
+
+## Report format
+
+Report only. **Never auto-fix a boundary violation** — the correct fix is a design decision (invert the dependency, move the code, or move the boundary), and only the last one is safe for an agent to pick.
+
+```
+ARCHITECTURE CHECK — <scope>
+
+VERDICT: PASS | FAIL | NO-BOUNDARIES-DECLARED
+
+Declared rules applied:
+  <rule text from AGENTS.md boundaries[]>
+
+VIOLATIONS (n)
+  [V1] <severity> <file>:<line>
+       Edge:  <source zone> → <target zone>
+       Rule:  "<the declared line this breaks>"
+       Why:   <what breaks downstream if this stands>
+       Fix:   <invert | relocate | introduce port | amend the boundary via ADR>
+
+SMELLS (n)  — not blocking
+  [S1] <file/area> — <pattern> → suggested boundary line: "<proposed rule>"
+
+PRE-EXISTING (n)  — not caused by this change
+  [P1] <file> — <rule broken> (unchanged by this diff)
+
+Unclassified files: <paths that map to no declared zone>
+```
+
+Severity: **high** = crosses a core boundary or reverses a dependency direction · **medium** = leaks a type or transitive hop · **low** = test-only or single-file convenience import.
+
+## Proactive Triggers
+
+- **A diff adds an import crossing two top-level directories** → run the check unasked and report the edge.
+- **A new `utils/`, `common/`, `helpers/`, or `shared/` module appears** → flag it; these become the transitive hop that launders every violation.
+- **A barrel/index file re-exports across zones** → flag it; barrels hide illegal edges from static review.
+- **`boundaries[]` is empty in a repo with clear layered structure** → propose the rule list before the first violation lands.
+- **The fix for a violation is "move the boundary"** → stop and route to the **adr-write** skill; changing a boundary is a recorded decision, not a diff.
+- **A file lands in `protectedPaths[]`** → STOP, regardless of dependency direction.
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---|---|
+| "Does this change break the architecture?" | Diff-scoped check report with PASS/FAIL and per-violation rule citation |
+| "Audit the repo's boundaries" | Full violation inventory, ranked by blast radius, with pre-existing debt separated |
+| "We have no boundaries declared" | Inferred architecture style + proposed `boundaries[]` lines ready for `AGENTS.md` |
+| "Is this import allowed?" | Single-edge ruling: allowed / forbidden / undeclared, with the rule quoted |
+| "How do I fix V2?" | The three options (invert, relocate, amend) with the trade-off of each — you choose |
+
+## Communication
+
+Bottom line first — the verdict. Quote the declared rule verbatim; never paraphrase it into something stricter. Tag confidence: 🟢 rule is explicit, 🟡 rule inferred from an ambiguous line, 🔴 no rule, reporting as smell. Say "no boundary declared" plainly rather than manufacturing one.
+
+## Related Skills
+
+- **adr-write**: Use when the right fix is to *move* a boundary. NOT for enforcing an existing one.
+- **spec-driven**: Use to check `plan.md` before tasks are written — cheapest place to catch a boundary problem. NOT for post-merge audits.
+- **onboard**: Use to discover module structure in an unfamiliar repo before boundaries can be declared. NOT once `boundaries[]` exists.
+- **security-review**: Use for input, auth, and dependency risk in the same diff. NOT for dependency *direction*.
+- **test-first**: Use when a violation exists because the code was untestable as designed — a hard-to-test seam is often a misplaced boundary.
+- **perf-budget**: Use when a boundary fix adds indirection that could cost latency or bundle size.
+- **handoff**: Use to record an unresolved violation so the next tool does not re-litigate it.
+- Commands: `/review` runs this over the working diff, `/verify` confirms the fix landed, `/adr` records a boundary change, `/plan` is where boundary questions belong first.

package/registry/skills/architecture-guard/references/boundary-patterns.md

@@ -0,0 +1,142 @@
+# Boundary patterns by architecture style
+
+Use this to interpret a declared `boundaries[]` line correctly for the style the repo actually uses. **This file describes what each style means — it does not declare rules for any repo.** The repo's `AGENTS.md` does that.
+
+Identify the style from the directory shape, then apply the matching rule set to classify edges.
+
+---
+
+## Layered (n-tier)
+
+**Shape:** `presentation/` → `application/` → `domain/` → `persistence/` (names vary: `ui`, `service`, `business`, `data`).
+
+**Rule:** dependencies point downward only. A layer may skip a layer only if declared; strict layering forbids even that.
+
+| Edge | Verdict |
+|---|---|
+| presentation → application | allowed |
+| application → domain | allowed |
+| domain → persistence | allowed in classic layered, **forbidden** in clean (see below) |
+| persistence → domain | violation (upward) |
+| presentation → persistence | violation in strict layering; smell in relaxed |
+| any → cross-cutting logging/config | allowed if declared as cross-cutting |
+
+**Signature of a violation:** an import in a lower-layer file whose path resolves to a higher layer. Also: a lower layer's public type mentioning a higher layer's type in a signature.
+
+**Trap:** DTOs. A `persistence` entity leaking into a `presentation` response is not an import violation but is a coupling violation if `boundaries[]` says layers exchange their own models.
+
+---
+
+## Clean / Onion
+
+**Shape:** concentric. `entities` / `domain` at the core, then `use-cases` / `application`, then `interface-adapters` (controllers, gateways, presenters), then `frameworks` / `infrastructure`.
+
+**Rule — the dependency rule:** source-code dependencies point **inward only**. Nothing in an inner circle knows anything about an outer circle.
+
+| Edge | Verdict |
+|---|---|
+| infrastructure → domain | allowed (this is the point) |
+| domain → infrastructure | **violation**, always |
+| use-case → repository *interface* declared in the core | allowed |
+| use-case → concrete repository class | violation — depend on the port |
+| domain → any framework/ORM/HTTP package | violation |
+| domain → standard library / language primitives | allowed |
+
+**Signature:** the core importing a package name that appears in the dependency manifest as a framework, ORM, HTTP client, or serializer. Grep the core for third-party package imports — in a healthy clean core, that list is nearly empty.
+
+**Trap:** annotations and decorators. An ORM annotation on a domain entity is a framework dependency even though it does not look like an import statement.
+
+---
+
+## Hexagonal (ports and adapters)
+
+**Shape:** `domain/` (or `core/`), `ports/` (interfaces), `adapters/` split into driving (inbound: HTTP, CLI, queue consumer) and driven (outbound: DB, mail, third-party API).
+
+**Rule:** the core defines ports. Adapters implement or invoke them. The core never names an adapter.
+
+| Edge | Verdict |
+|---|---|
+| driving adapter → port (inbound interface) | allowed |
+| core → outbound port interface | allowed — the core owns it |
+| core → driven adapter implementation | **violation** |
+| driven adapter → core domain types | allowed |
+| adapter → adapter | violation — adapters compose through the core |
+| port interface → framework type in its signature | violation — the port is leaking the outside in |
+
+**Signature:** a `new ConcreteAdapter()` or direct construction inside the core; a port signature containing an HTTP request/response, ORM entity, or SDK type.
+
+**Trap:** "the port is in the adapter folder." If the interface lives with its implementation, the dependency is not actually inverted — the core still points outward at compile time. That is a real violation even though the names look right.
+
+---
+
+## Vertical slice / feature-sliced
+
+**Shape:** `features/<feature>/` each containing its own handlers, models, and data access; plus a `shared/` or `common/`.
+
+**Rule:** features are isolated. Slices depend on shared, never on each other.
+
+| Edge | Verdict |
+|---|---|
+| feature → shared | allowed |
+| feature-a → feature-b | **violation** (sibling coupling) |
+| feature → its own internals | allowed |
+| shared → any feature | violation — shared must not know its consumers |
+| feature-a → feature-b via an event/message contract in shared | allowed; that is the sanctioned path |
+
+**Signature:** any import path containing a second `features/<name>/` segment different from the importing file's own.
+
+**Trap:** `shared/` becoming a dumping ground. Every sibling-coupling problem gets "solved" by promoting code to shared until shared *is* the application. Flag growth in shared as a smell even when no rule is broken.
+
+---
+
+## Modular monolith
+
+**Shape:** `modules/<module>/` with an explicit public surface (`index`, `api/`, `contracts/`, or a language-level `public`/`internal` marker) and private internals.
+
+**Rule:** modules communicate only through published surfaces. Internals are unreachable.
+
+| Edge | Verdict |
+|---|---|
+| module-a → module-b's public api | allowed |
+| module-a → module-b's internal file | **violation** (deep import) |
+| module → platform/kernel shared services | allowed if declared |
+| module-b's public api exposing an internal type | violation — the surface leaks |
+| module-a → module-b, and module-b → module-a | violation of acyclicity even if both go through public api |
+
+**Signature:** an import path that reaches past the module's declared entry segment. Cycles between module pairs.
+
+**Trap:** database-level coupling. Two modules sharing a table is a boundary violation with zero import evidence. Check migrations and query targets when the declared boundary mentions data ownership.
+
+---
+
+## FSD (Feature-Sliced Design)
+
+**Shape:** layers, top to bottom — `app` → `pages` (or `views`) → `widgets` → `features` → `entities` → `shared`. Each layer contains slices; each slice has segments (`ui`, `model`, `api`, `lib`).
+
+**Rule:** a slice may import only from layers strictly **below** it, and only from another slice's public entry — never sideways within the same layer.
+
+| Edge | Verdict |
+|---|---|
+| pages → widgets, features, entities, shared | allowed |
+| features → entities, shared | allowed |
+| entities → shared | allowed |
+| entities → features | **violation** (upward) |
+| feature-a → feature-b | **violation** (same-layer sideways) |
+| any → another slice's internal segment, bypassing its entry | violation (deep import) |
+| shared → anything above it | violation |
+
+**Signature:** import path layer index ≥ the importing file's layer index; or a path with more segments than the slice's public entry.
+
+**Trap:** `widgets` used as an escape hatch to compose two features that should not know each other. That is the sanctioned place for such composition — verify it is actually a widget and not a feature in disguise.
+
+---
+
+## Cross-style notes
+
+**Cross-cutting concerns** (logging, config, telemetry, error types) are allowed everywhere *only when declared as cross-cutting*. Otherwise a logging import into the core is a framework dependency like any other.
+
+**Test code** commonly gets relaxed rules — reaching into internals to set up fixtures. Apply the relaxation only if `boundaries[]` grants it. If tests routinely need deep imports, that is evidence the public surface is wrong; report it as a smell.
+
+**Generated code** (clients, migrations, protobuf output) should be excluded by an explicit declared exemption, not by your judgment. If there is no exemption and generated code violates a boundary, report it as a violation with a note that an exemption is probably the right fix.
+
+**Build-time vs runtime edges.** A type-only import erased at build time is still a compile-time dependency and still a violation under most declared rules, though at lower severity. Dependency injection registration is a real edge even when the concrete type appears only in a composition root — and the composition root is normally the one place allowed to see everything.