boundry 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to Boundry are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versioning follows [semver](https://semver.org/).
+
+## [0.3.0] — unreleased
+
+Makes the "one file can be both the communication diagram and the enforcement
+model" promise hold for deep, nested C4 trees.
+
+### Added
+
+- **File-level mapping — `metadata { file 'src/x.ts' }`** ([#3]). An element maps
+  to a single file instead of a folder. A file module owns exactly its file; a
+  folder module owns its subtree minus any mapped descendants — nested folders
+  and file leaves alike.
+  - This is what lets a deep nested diagram stay legal *and* enforceable. A
+    guarded contract or port that sits beside sibling sub-folders can be a file
+    leaf rather than collapsing into its parent folder. Collapsed, its edges
+    become ancestor↔descendant, which LikeC4 rejects with
+    `Invalid parent-child relationship`; as a leaf they stay sibling-to-sibling.
+  - Declaring both `folder` and `file` on one element is an error.
+
+### Changed
+
+- **`Module.folder: string` → `Module.path: string` + `Module.kind: 'folder' | 'file'`.**
+  SDK-breaking; the diagram surface and CLI are unaffected.
+
+[#3]: https://github.com/makspiechota/boundry/issues/3
+
+## [0.2.0] — 2026-07-16
+
+The release that makes the diagram a *governed* artifact rather than just a
+source of rules. An agent can now be handed the diagram without being handed the
+ability to grant itself dependencies.
+
+### Added
+
+- **Approval lifecycle — `#proposed`.** An edge marked `#proposed` is intent, not
+  permission: it is excluded from the allow-list, so `check` stays red until a
+  human approves. Mark an element too and the reviewer sees the new box as well
+  as the new arrow.
+  - On an **edge** the marker is semantic (the edge grants nothing until
+    approved). On an **element** it is visual only — a module is enforced from
+    the moment it is drawn, which is safe, because a module grants nothing until
+    an edge permits it. **The edge is always the only grant.**
+- **`boundry approve`** — strips `#proposed` markers deterministically by
+  splicing the LikeC4 CST. Never an LLM edit: source-preserving, idempotent, and
+  byte-exact. Approval is a human act; this command is the human's.
+- **`boundry verify --base <ref>`** — compares the working diagram against an
+  approved git ref and rejects any edge granted *without* going through a
+  proposal. Because proposals are excluded from the allow-list, the set of
+  newly-allowed edges is exactly the set of self-approvals. `approve --base` uses
+  the same gate, so it refuses to launder a self-granted edge.
+- **`governRoot` (opt-in)** ([#1]) — `metadata { governRoot 'src' }` declares a code
+  root fully governed: importing territory under it that no module claims is a
+  violation rather than free, and `check` warns about code no module covers. The
+  mirror of the zero-files warning. Without it, unmapped folders stay ignored, so
+  a communication diagram still works as an enforcement diagram.
+- **`#anything` wildcard** — a box tagged `#anything` maps to no folder and stands
+  for the rest of the code; a module with an edge into it is exempt from every
+  rule. This is the explicit way to say "deliberately unconstrained", for the
+  composition root that must import everything to wire it together.
+  - It rides the same protocol as any other edge: `#proposed` suppresses it until
+    approved, and `verify` reports a self-granted wildcard edge like any other.
+  - Prior to this, the only way to let `src/index.ts` wire things up under a
+    govern root was to leave it *unmapped* — granting the same power by
+    **omission**, with nothing drawn for a reviewer to see.
+  - The exemption belongs to the wired module alone and does not leak.
+- **`exemptImporters`** ([#2]) — `metadata { exemptImporters '/__tests__/|\\.d\\.ts$' }`
+  drops matched files from every rule's `from` side: they are analysed, but never
+  held to a boundary as an importer. For test files that legitimately wire real
+  adapters across layers, and for ambient `.d.ts` declarations.
+  - **From-side only.** Exempt files stay governed as import *targets*, so
+    production importing a test helper is still a violation.
+  - Patterns are regexes and union across every element that declares one.
+    LikeC4 has no repeated metadata keys, so use a `|` alternation or one per
+    element. **Backslashes must be doubled** — LikeC4 processes string escapes,
+    so `'\.d\.ts$'` arrives as `.d.ts$` and over-matches silently.
+  - `check` warns when an exemption matches **zero** files or **every** file;
+    both mean the pattern is wrong. An invalid or empty pattern is a hard error.
+  - `verify` reports an exemption added since the base, like any other grant.
+- **Skill for coding agents** — `.claude/skills/define-architecture-boundaries`
+  documents the annotations and the proposal protocol, including the things an
+  agent must never do: add a bare edge, strip a marker, run `approve`, draw a
+  wildcard, or route around a boundary through an unmodelled folder.
+- **Nesting support.** A module owns its folder *minus* any mapped descendants,
+  so a parent's edges govern only the parent's own files. A child never inherits
+  them and must be permitted explicitly; a connection between two subtrees never
+  permits every child pair across them.
+
+### Fixed
+
+- **A check that analysed zero files reported success.** `check` now throws when
+  dependency-cruiser sees no sources — the setup being broken is a failure, not a
+  clean run. This is the guard that caught the 0.1.0 packaging bug below.
+
+### Changed
+
+- **`Pipeline.verify()` returns `VerifyResult`** (`{ edges, exemptions }`) rather
+  than a bare edge array, so both kinds of grant surface. SDK-breaking; the CLI
+  is unaffected.
+
+[#1]: https://github.com/makspiechota/boundry/issues/1
+[#2]: https://github.com/makspiechota/boundry/issues/2
+
+## [0.1.1] — never released
+
+Tagged locally, never published or pushed; its contents ship as part of 0.2.0.
+
+### Fixed
+
+- **`typescript` moved to `dependencies`.** dependency-cruiser needs it at
+  runtime to parse `.ts`; as a devDependency it was absent from a real install.
+- **Stale `dist/` artifacts in the published tarball.** `build` now cleans first,
+  so a restructure can't leave orphaned files from a previous layout.
+
+## [0.1.0] — 2026-07 — **deprecated, do not use**
+
+**This version silently enforces nothing.** `typescript` was a devDependency, so
+in a clean install dependency-cruiser could not parse TypeScript and reported
+`✓ no boundary violations` while checking zero files. A guardrail that fails open
+is worse than none. Upgrade.
+
+## [0.0.1]
+
+First publish. Compiles a LikeC4 diagram into dependency-cruiser rules:
+`metadata { folder '…' }` maps an element to a folder, every drawn relationship
+is an allowed dependency, and everything undrawn is forbidden. Commands: `check`,
+`generate`.

package/README.md

@@ -18,8 +18,9 @@ diagram (LikeC4)  ──►  boundary model  ──►  dependency-cruiser rules
 
 ## How it works
 
-1. You annotate each element in your diagram with the folder it owns:
-   `metadata { folder 'src/domain' }`.
+1. You annotate each element in your diagram with the source it owns — a folder,
+   `metadata { folder 'src/domain' }`, or a single file,
+   `metadata { file 'src/ports/contract.ts' }`.
 2. Every relationship you draw (`a -> b`) is an **allowed** dependency.
    Anything you don't draw is **forbidden**.
 3. Boundry lifts the diagram into a source-agnostic boundary model, compiles a
@@ -47,6 +48,99 @@ mirror of the zero-files warning: the model failing to cover the code is as much
 a gap as the code failing to back the model. Nothing changes unless you declare
 it.
 
+A mapped folder claims its **entire subtree**, so the abstraction level stays
+yours: one box on `src/domain` covers everything beneath it. You add finer boxes
+where you want finer *rules*, not to satisfy the coverage check.
+
+### Mapping a single file (deep nested diagrams)
+
+A rich C4 model nests: `application` › `metrics` › `ports` › `story-points-read`
+› `stub`, with a drill-down view at each level. Sometimes a *file* is the guarded
+thing — a contract, a port, a single repository — sitting beside its sibling
+sub-folders. Map it to a file instead of a folder:
+
+```likec4
+component ports 'ports' {
+  metadata { folder 'src/ports' }
+
+  component store 'in-memory-store' {
+    metadata { file 'src/ports/in-memory-store.ts' }   // a leaf, not a folder
+  }
+  component read 'story-points-read' {
+    metadata { folder 'src/ports/story-points-read' }
+    component stub 'stub' {
+      metadata { folder 'src/ports/story-points-read/stub' }
+    }
+  }
+}
+
+stub -> store   // a legal cross-subtree edge
+```
+
+This is what lets a deep tree be **both** the documentation and the enforcement
+model. Collapse that file into its parent folder and the edge becomes
+`stub -> ports` — a descendant importing its ancestor, which LikeC4 rejects with
+`Invalid parent-child relationship`. As a file leaf, `store` is a sibling, so the
+edge is legal *and* Boundry governs the file exactly: only `stub` may import it,
+and the surrounding `ports` folder no longer owns it.
+
+A file module owns exactly its file; a folder module owns its subtree minus any
+mapped descendants — nested folders and file leaves alike.
+
+### Exempting test files and ambient declarations
+
+Every file under a mapped folder is governed as a rule *source* by default —
+including tests. An integration test that wires a real database adapter across a
+layer boundary is doing its job, not breaking the architecture. Exempt them:
+
+```likec4
+system app 'App' {
+  metadata {
+    exemptImporters '/__tests__/|\\.d\\.ts$'
+  }
+}
+```
+
+Matched files are still analysed, but they are dropped from every rule's `from`
+side, so they may import anything. This is **from-side only** — they stay
+governed as import *targets*, so production reaching into a test helper is as
+forbidden as it ever was. Patterns are regexes, union across every element that
+declares one, and change nothing unless you declare one.
+
+> **Double your backslashes.** LikeC4 processes string escapes, so `'\.d\.ts$'`
+> arrives as `.d.ts$`, where `.` is a wildcard that matches far more than you
+> meant. Write `'\\.d\\.ts$'`. Boundry warns when an exemption matches **zero**
+> files, or when one matches **every** file, since both mean the pattern is
+> wrong.
+
+An exemption is a grant — it lifts whole files out of every rule — so `verify`
+reports one added since the approved base, exactly like an undrawn edge.
+
+### The composition root — `#anything`
+
+Every repo has one place that legitimately imports everything: the entry point
+that constructs the object graph. Give it a module and wire it to a wildcard:
+
+```likec4
+  // Owns 'src' minus every mapped descendant — the loose files at the root.
+  module entry 'Composition root' {
+    metadata { folder 'src' }
+  }
+  element anything 'Anything' {
+    #anything
+  }
+
+  entry -> anything
+```
+
+A box tagged `#anything` maps to no folder and stands for "the rest of the code".
+A module with an edge into it is exempt from every rule — and only that module;
+the exemption doesn't leak.
+
+The alternative was to leave `src/index.ts` unmapped, which grants it the same
+freedom by **omission**: nothing drawn, nothing to review. The wildcard makes the
+exemption a visible box someone approved on purpose.
+
 ## See it
 
 The diagram you draw *is* the whole spec. Below is the example architecture that
@@ -111,11 +205,49 @@ npx boundry check --arch arch src
 
 A `domain → infra` import is now a build failure; `infra → domain` is fine.
 
+## Changing the architecture — propose, approve, commit
+
+If agents can edit the diagram, they can grant themselves any dependency they
+like, and the guardrail is theatre. So a change to the architecture goes through
+a lifecycle:
+
+**propose** → **approve** → **commit**
+
+An agent blocked by a boundary adds the edge **with a marker**:
+
+```likec4
+  domain -> shared #proposed
+```
+
+A `#proposed` edge is *intent, not permission*. It's excluded from the allow-list,
+so `check` stays red and the agent stays blocked. It has asked, not taken.
+
+A human approves by stripping the marker — that's what `boundry approve` does,
+deterministically, by splicing the LikeC4 CST. No model call, no reformatting:
+source-preserving, idempotent, byte-exact.
+
+```bash
+boundry verify --arch arch --base origin/main   # any edge granted without a marker?
+boundry approve --arch arch --base origin/main  # HUMAN ONLY: strip markers = approve
+```
+
+`verify` compares against the approved diagram at a git ref and rejects edges that
+appeared *without* going through a proposal. Because proposals are excluded from
+the allow-list, the newly-allowed set is exactly the set of self-approvals — no
+diff engine required. `approve --base` runs the same gate first, so it won't
+launder a self-granted edge into an approved one.
+
+Point your agents at
+[`.claude/skills/define-architecture-boundaries`](.claude/skills/define-architecture-boundaries/SKILL.md)
+and they'll follow this protocol.
+
 ## CLI
 
 ```
 boundry check    [--arch <dir>] [--cwd <dir>] [sources...]
 boundry generate [--arch <dir>] [--cwd <dir>] [--out <file>]
+boundry verify   [--arch <dir>] [--cwd <dir>] --base <git-ref>
+boundry approve  [--arch <dir>] [--cwd <dir>] [--base <git-ref>]
 ```
 
 | Flag | Meaning |
@@ -123,14 +255,18 @@ boundry generate [--arch <dir>] [--cwd <dir>] [--out <file>]
 | `--arch <dir>` | LikeC4 workspace directory (all `.likec4` files in it are merged). Default `.`. |
 | `--cwd <dir>` | Repo root to check. `folder` paths are relative to it. Lets you run from anywhere. |
 | `--out <file>` | `generate` only: where to write the dependency-cruiser config. Default `.dependency-cruiser.cjs`. |
+| `--base <ref>` | `verify`/`approve`: the git ref holding the approved diagram to compare against. |
 | `sources...` | `check` only: paths to lint. Default `src`. |
 
 - **`check`** compiles the rules and runs the linter. Exits non-zero on any violation.
 - **`generate`** just emits the dependency-cruiser config so you can commit it or
   run `depcruise` yourself.
+- **`verify`** rejects dependencies granted without a proposal.
+- **`approve`** strips `#proposed` markers. For humans, not agents.
 
-Boundry warns (but does not fail) when a mapped folder matches **zero** files —
-so a passing check can never silently enforce nothing.
+Boundry warns (but does not fail) when a mapped folder matches **zero** files, and
+**fails outright** when a check analysed no files at all — so a passing check can
+never silently enforce nothing. A guardrail that fails open is worse than none.
 
 ## CI
 
@@ -147,6 +283,9 @@ jobs:
         with: { node-version: 20 }
       - run: npm ci
       - run: npx boundry check --arch arch src
+      # On PRs, also reject dependencies granted without a proposal.
+      - run: npx boundry verify --arch arch --base origin/${{ github.base_ref }}
+        if: github.event_name == 'pull_request'
 ```
 
 ## Programmatic use (SDK)
@@ -181,11 +320,17 @@ without touching the core.
 
 Current limitations:
 
-- One element maps to exactly one folder.
+- One element maps to exactly one path — a folder or a single file.
 - Nesting is supported: you can map a parent folder *and* its children. A
   parent's edges govern only the parent's own files — a child never inherits
   them and must be permitted explicitly.
 - `folder` paths are relative to the repo root (`--cwd`), not the diagram file.
+- With a `governRoot`, unmapped code is blocked as an import *target* but is not
+  yet constrained as an *importer* — rules are generated per mapped module, so
+  unmapped code has no rules of its own.
+
+See the [changelog](./CHANGELOG.md) for what's in each release.
+**`0.1.0` is deprecated** — it silently enforces nothing (see the changelog).
 
 ## License
 

package/dist/adapters/enforcer/depcruiser.d.ts

@@ -1,5 +1,5 @@
 import type { EnforcerPort, EnforcerConfig, CheckResult } from '../../core/ports/ports.js';
-import type { BoundaryModel } from '../../core/model/boundary-model.js';
+import { type BoundaryModel } from '../../core/model/boundary-model.js';
 /** First enforcer adapter: targets dependency-cruiser for TypeScript. */
 export declare class DepCruiserEnforcer implements EnforcerPort {
     render(model: BoundaryModel): EnforcerConfig;

package/dist/adapters/enforcer/depcruiser.js

@@ -1,17 +1,35 @@
 import * as dependencyCruiser from 'dependency-cruiser';
+import { unconstrainedModules, } from '../../core/model/boundary-model.js';
 // dependency-cruiser ships CommonJS; reach `cruise` through either interop shape.
 const cruise = dependencyCruiser.cruise ?? dependencyCruiser.default?.cruise;
-function folderPrefix(folder) {
-    return folder.replace(/\/+$/, '');
+function normalizePath(path) {
+    return path.replace(/\/+$/, '');
 }
-function folderToRegex(folder) {
-    const escaped = folderPrefix(folder).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    return `^${escaped}/`;
+function escapeRegex(path) {
+    return normalizePath(path).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-/** True if `child` is a folder strictly nested under `parent`. */
-function isDescendantFolder(child, parent) {
-    const c = folderPrefix(child);
-    const p = folderPrefix(parent);
+/**
+ * The regex matching exactly the sources a module owns: everything under a
+ * folder (`^src/core/`), or a single file exactly (`^src/x.ts$`).
+ */
+function moduleScopeRegex(m) {
+    return m.kind === 'file' ? `^${escapeRegex(m.path)}$` : `^${escapeRegex(m.path)}/`;
+}
+/** True if `source` (a file path) belongs to module `m`, ignoring descendants. */
+function ownsSource(m, source) {
+    const p = normalizePath(m.path);
+    return m.kind === 'file' ? source === p : source.startsWith(`${p}/`);
+}
+/**
+ * True if module `child` is nested strictly under module `parent`. Only a folder
+ * can contain anything; a file (or a folder equal to the child) contains nothing.
+ * A folder nesting a file leaf counts — that is the whole point of file mapping.
+ */
+function isNestedUnder(child, parent) {
+    if (parent.kind === 'file')
+        return false;
+    const c = normalizePath(child.path);
+    const p = normalizePath(parent.path);
     return c !== p && c.startsWith(`${p}/`);
 }
 /**
@@ -28,18 +46,34 @@ function buildForbiddenRules(model) {
         allowedTargets.set(m.id, new Set([m.id]));
     for (const edge of model.allowed)
         allowedTargets.get(edge.from)?.add(edge.to);
-    // Each module's scope: its folder, carving out any mapped descendant folders.
+    // Each module's scope: its path, carving out any mapped descendants (a nested
+    // folder OR a mapped file leaf living inside it — both belong to their own,
+    // more-specific module).
     const scopeOf = new Map();
     for (const m of model.modules) {
         const descendants = model.modules
-            .filter((other) => isDescendantFolder(other.folder, m.folder))
-            .map((other) => folderToRegex(other.folder));
+            .filter((other) => isNestedUnder(other, m))
+            .map((other) => moduleScopeRegex(other));
         scopeOf.set(m.id, descendants.length
-            ? { path: folderToRegex(m.folder), pathNot: descendants }
-            : { path: folderToRegex(m.folder) });
+            ? { path: moduleScopeRegex(m), pathNot: descendants }
+            : { path: moduleScopeRegex(m) });
     }
+    // Exemptions apply to the `from` side only: matched files may import freely,
+    // but every module's scope still governs them as a *target*, so importing a
+    // test helper from production stays forbidden.
+    const asImporter = (id) => {
+        const scope = scopeOf.get(id);
+        if (model.exemptImporters.length === 0)
+            return scope;
+        return { ...scope, pathNot: [...(scope.pathNot ?? []), ...model.exemptImporters] };
+    };
+    // A module wired to an `#anything` wildcard is deliberately exempt: it is the
+    // composition root, whose job is to import everything and wire it together.
+    const unconstrained = unconstrainedModules(model);
     const rules = [];
     for (const from of model.modules) {
+        if (unconstrained.has(from.id))
+            continue;
         const allowed = allowedTargets.get(from.id);
         for (const to of model.modules) {
             if (allowed.has(to.id))
@@ -48,7 +82,7 @@ function buildForbiddenRules(model) {
                 name: `boundary:${from.id}->${to.id}`,
                 comment: `${from.title} may not depend on ${to.title}`,
                 severity: 'error',
-                from: scopeOf.get(from.id),
+                from: asImporter(from.id),
                 to: scopeOf.get(to.id),
             });
         }
@@ -57,14 +91,17 @@ function buildForbiddenRules(model) {
     // module claims is forbidden, not free. Additive — the pair rules above still
     // decide every mapped-to-mapped edge on their own.
     if (model.governRoot) {
-        const claimed = model.modules.map((m) => folderToRegex(m.folder));
+        const rootAsFolder = { id: '', title: '', path: model.governRoot, kind: 'folder' };
+        const claimed = model.modules.map(moduleScopeRegex);
         for (const from of model.modules) {
+            if (unconstrained.has(from.id))
+                continue;
             rules.push({
                 name: `boundary:${from.id}->unmapped`,
                 comment: `${from.title} may not depend on code under '${model.governRoot}' that no module claims`,
                 severity: 'error',
-                from: scopeOf.get(from.id),
-                to: { path: folderToRegex(model.governRoot), pathNot: claimed },
+                from: asImporter(from.id),
+                to: { path: moduleScopeRegex(rootAsFolder), pathNot: claimed },
             });
         }
     }
@@ -98,27 +135,52 @@ module.exports = {
         const violations = raw
             .filter((v) => v.rule?.severity === 'error')
             .map((v) => ({ from: v.from, to: v.to, rule: v.rule?.name ?? 'unknown' }));
-        // A module whose folder matched no source files enforces nothing — the
+        // A module whose path matched no source files enforces nothing — the
         // "green but inert" trap. Surface it so a passing check can't hide it.
         const seen = (output?.modules ?? []).map((m) => String(m.source));
+        // A guardrail that analysed nothing must never report success. Seeing zero
+        // sources means the setup is broken (wrong paths, or no TypeScript for
+        // dependency-cruiser to parse with) — that is a failure, not a clean run.
+        if (seen.length === 0) {
+            throw new Error(`analysed 0 source files under '${sources.join(', ')}' — nothing was enforced. ` +
+                'Check the source paths, and that TypeScript is installed alongside Boundry.');
+        }
         const warnings = [];
         for (const mod of model.modules) {
-            const prefix = `${mod.folder.replace(/\/+$/, '')}/`;
-            if (!seen.some((source) => source.startsWith(prefix))) {
-                warnings.push(`module '${mod.title}' maps to '${mod.folder}', which matched 0 source files`);
+            if (!seen.some((source) => ownsSource(mod, source))) {
+                warnings.push(`module '${mod.title}' maps to '${mod.path}', which matched 0 source files`);
             }
         }
+        // An exemption is a grant, so a dead one is worth knowing about: it means
+        // the pattern is wrong (LikeC4 eats backslashes) and files the author meant
+        // to exempt are still being policed — or were never there to begin with.
+        const exemptions = model.exemptImporters.map((pattern) => ({
+            pattern,
+            matches: seen.filter((source) => new RegExp(pattern).test(source)),
+        }));
+        for (const { pattern, matches } of exemptions) {
+            if (matches.length === 0) {
+                warnings.push(`exemption '${pattern}' matched 0 source files`);
+            }
+            else if (matches.length === seen.length) {
+                warnings.push(`exemption '${pattern}' matched every source file — no file can violate a boundary`);
+            }
+        }
+        const isExempt = (source) => model.exemptImporters.some((pattern) => new RegExp(pattern).test(source));
         // The symmetric guard: code under a declared govern root that no module
         // claims. The model not covering the code is as much a gap as the code not
         // backing the model.
         if (model.governRoot) {
-            const rootPrefix = `${folderPrefix(model.governRoot)}/`;
-            const claimed = model.modules.map((m) => `${folderPrefix(m.folder)}/`);
+            const rootPrefix = `${normalizePath(model.governRoot)}/`;
             const unclaimed = new Set();
             for (const source of seen) {
                 if (!source.startsWith(rootPrefix))
                     continue;
-                if (claimed.some((prefix) => source.startsWith(prefix)))
+                if (model.modules.some((m) => ownsSource(m, source)))
+                    continue;
+                // Exempt code is deliberately outside the architecture; asking a module
+                // to claim it would defeat the point of exempting it.
+                if (isExempt(source))
                     continue;
                 unclaimed.add(source.slice(0, source.lastIndexOf('/')));
             }

package/dist/adapters/visualizer/likec4.js

@@ -1,52 +1,54 @@
 import { LikeC4 } from 'likec4';
 import { readFileSync, writeFileSync } from 'node:fs';
-function findDescendant(node, predicate) {
-    const seen = new Set();
-    const stack = [node];
-    while (stack.length) {
-        const n = stack.pop();
-        if (!n || typeof n !== 'object' || seen.has(n))
-            continue;
-        seen.add(n);
-        if (Array.isArray(n)) {
-            stack.push(...n);
-            continue;
-        }
-        if (predicate(n))
-            return n;
-        for (const key of Object.keys(n)) {
-            if (!key.startsWith('$'))
-                stack.push(n[key]);
-        }
+/**
+ * An exemption pattern has to be a usable regex before it reaches the linter. A
+ * broken or empty one would otherwise be a silent hole: it exempts files from
+ * every rule, so failing to compile it must be loud, never shrugged off.
+ *
+ * Note LikeC4 string literals process escapes, so `'\.d\.ts$'` arrives here as
+ * `.d.ts$` — a regex where `.` is a wildcard. Patterns must be written
+ * `'\\.d\\.ts$'` in the diagram. That silent widening is why an exemption that
+ * matches nothing is reported at check time.
+ */
+function assertUsableRegex(pattern, elementId) {
+    if (pattern.trim() === '') {
+        throw new Error(`element '${elementId}' declares an empty exemption pattern, which would exempt every file`);
+    }
+    try {
+        new RegExp(pattern);
     }
-    return undefined;
+    catch (cause) {
+        throw new Error(`element '${elementId}' declares an exemption pattern that is not a valid regex: ` +
+            `'${pattern}' (${cause.message}). Remember LikeC4 eats backslashes — ` +
+            'write \\\\. to mean a literal dot.');
+    }
+    return pattern;
 }
+/** A `#proposed` marker in the source — on an element or a relationship alike. */
 function isProposedTag(node, text) {
     return (node.$type === 'TagRef' &&
         node.$cstNode &&
         text.slice(node.$cstNode.offset, node.$cstNode.end) === '#proposed');
 }
 /**
- * For a relationship carrying a `#proposed` marker, the range of source to
- * remove: the whole relationship body (the proposal decoration) plus the
- * whitespace before it, or the bare inline tag when there is no body.
+ * The source to remove for one marker. A marker alone on its line takes the
+ * whole line (so approving leaves no blank gap); an inline one takes just the
+ * token and the space before it. The `tag proposed` declaration in the
+ * specification is untouched — the vocabulary stays for the next proposal.
  */
-function proposedRemovalRange(relation, text) {
-    const body = findDescendant(relation, (n) => n.$type === 'RelationBody' && n.$cstNode);
-    if (body) {
-        let start = body.$cstNode.offset;
-        while (start > 0 && /\s/.test(text[start - 1]))
-            start--;
-        return { start, end: body.$cstNode.end };
-    }
-    const tag = findDescendant(relation, (n) => isProposedTag(n, text));
-    if (tag) {
-        let start = tag.$cstNode.offset;
-        while (start > 0 && (text[start - 1] === ' ' || text[start - 1] === '\t'))
-            start--;
-        return { start, end: tag.$cstNode.end };
+function proposedRemovalRange(tag, text) {
+    const { offset, end } = tag.$cstNode;
+    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
+    const lineEnd = text.indexOf('\n', end);
+    const beforeOnLine = text.slice(lineStart, offset);
+    const afterOnLine = text.slice(end, lineEnd === -1 ? text.length : lineEnd);
+    if (beforeOnLine.trim() === '' && afterOnLine.trim() === '') {
+        return { start: lineStart, end: lineEnd === -1 ? end : lineEnd + 1 };
     }
-    return undefined;
+    let start = offset;
+    while (start > lineStart && (text[start - 1] === ' ' || text[start - 1] === '\t'))
+        start--;
+    return { start, end };
 }
 function collectProposedRanges(root, text) {
     const ranges = [];
@@ -60,12 +62,8 @@ function collectProposedRanges(root, text) {
                 walk(item);
             return;
         }
-        if (node.$type === 'Relation' &&
-            node.$cstNode &&
-            findDescendant(node, (n) => isProposedTag(n, text))) {
-            const range = proposedRemovalRange(node, text);
-            if (range)
-                ranges.push(range);
+        if (isProposedTag(node, text)) {
+            ranges.push(proposedRemovalRange(node, text));
         }
         for (const key of Object.keys(node)) {
             if (!key.startsWith('$'))
@@ -90,21 +88,50 @@ export class LikeC4Visualizer {
         const likec4 = await LikeC4.fromWorkspace(this.workspaceDir);
         const model = await likec4.computedModel();
         const modules = [];
-        const folderIds = new Set();
+        const moduleIds = new Set();
+        const wildcardIds = new Set();
+        const exemptImporters = new Set();
         let governRoot;
         for (const el of model.elements()) {
+            // Any element may exempt importers; the patterns union across the
+            // diagram. LikeC4 forbids a repeated metadata key, so several patterns
+            // means either a `|` alternation or one per element.
+            const exemptMeta = el.getMetadata('exemptImporters');
+            for (const raw of Array.isArray(exemptMeta) ? exemptMeta : exemptMeta ? [exemptMeta] : []) {
+                exemptImporters.add(assertUsableRegex(raw, String(el.id)));
+            }
             // Opt-in: any element may declare the code root as fully governed. It
             // needs no `folder` of its own — it is a declaration, not a module.
             const rootMeta = el.getMetadata('governRoot');
             const declaredRoot = Array.isArray(rootMeta) ? rootMeta[0] : rootMeta;
             if (declaredRoot && !governRoot)
                 governRoot = declaredRoot;
-            const meta = el.getMetadata('folder');
-            const folder = Array.isArray(meta) ? meta[0] : meta;
-            if (folder) {
+            // A box tagged `#anything` is a wildcard, not a module: it maps to no
+            // folder and stands for the rest of the code. An edge into it exempts the
+            // source from every rule.
+            if (el.tags.some((tag) => String(tag) === 'anything')) {
+                wildcardIds.add(String(el.id));
+                continue;
+            }
+            // An element maps to a folder (owns its subtree) or a single file (owns
+            // exactly itself). A file leaf keeps a guarded contract sitting beside its
+            // sibling sub-folders, so a deep nested diagram stays legal AND enforceable.
+            const folderMeta = el.getMetadata('folder');
+            const fileMeta = el.getMetadata('file');
+            const folder = Array.isArray(folderMeta) ? folderMeta[0] : folderMeta;
+            const file = Array.isArray(fileMeta) ? fileMeta[0] : fileMeta;
+            if (folder && file) {
+                throw new Error(`element '${String(el.id)}' declares both 'folder' and 'file' — a module maps to one path`);
+            }
+            if (folder || file) {
                 const id = String(el.id);
-                modules.push({ id, title: el.title, folder });
-                folderIds.add(id);
+                modules.push({
+                    id,
+                    title: el.title,
+                    path: (folder ?? file),
+                    kind: folder ? 'folder' : 'file',
+                });
+                moduleIds.add(id);
             }
         }
         const allowed = [];
@@ -115,11 +142,20 @@ export class LikeC4Visualizer {
                 continue;
             const from = String(rel.source.id);
             const to = String(rel.target.id);
-            if (from !== to && folderIds.has(from) && folderIds.has(to)) {
+            // An edge into a wildcard is kept like any other grant, so `verify` sees a
+            // self-granted `#anything` exemption as the newly-allowed edge it is.
+            const targetGoverned = moduleIds.has(to) || wildcardIds.has(to);
+            if (from !== to && moduleIds.has(from) && targetGoverned) {
                 allowed.push({ from, to });
             }
         }
-        return { modules, allowed, governRoot };
+        return {
+            modules,
+            allowed,
+            governRoot,
+            wildcards: [...wildcardIds],
+            exemptImporters: [...exemptImporters],
+        };
     }
     /**
      * Deterministically strip `#proposed` markers from the diagram source,

package/dist/cli/index.js

@@ -46,10 +46,21 @@ function materializeArchAt(archDir, ref) {
     }
     return workDir;
 }
-function listGrantedEdges(granted) {
-    for (const edge of granted)
+function countGrants(granted) {
+    return granted.edges.length + granted.exemptions.length;
+}
+function listGrants(granted) {
+    for (const edge of granted.edges)
         console.error(`  ${edge.from} → ${edge.to}`);
-    console.error('  Mark them #proposed so the grant is an explicit, reviewable act.');
+    for (const pattern of granted.exemptions) {
+        console.error(`  exemption '${pattern}' — lifts matching files out of every rule`);
+    }
+    if (granted.edges.length > 0) {
+        console.error('  Mark them #proposed so the grant is an explicit, reviewable act.');
+    }
+    if (granted.exemptions.length > 0) {
+        console.error('  An exemption cannot be proposed — a human adds it to the diagram, or not at all.');
+    }
 }
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
@@ -97,12 +108,12 @@ async function main() {
             return;
         }
         const granted = await grantedSince(baseRef);
-        if (granted.length === 0) {
-            console.log(`Boundry: ✓ no edges granted without a #proposed marker (vs ${baseRef})`);
+        if (countGrants(granted) === 0) {
+            console.log(`Boundry: ✓ nothing granted without a #proposed marker (vs ${baseRef})`);
             return;
         }
-        console.error(`Boundry: ✗ ${granted.length} edge(s) granted without a #proposed marker (vs ${baseRef})`);
-        listGrantedEdges(granted);
+        console.error(`Boundry: ✗ ${countGrants(granted)} grant(s) made without a #proposed marker (vs ${baseRef})`);
+        listGrants(granted);
         process.exitCode = 1;
         return;
     }
@@ -110,9 +121,9 @@ async function main() {
         // Approving must never launder an edge that skipped the proposal protocol.
         if (baseRef) {
             const granted = await grantedSince(baseRef);
-            if (granted.length > 0) {
-                console.error(`Boundry: ✗ refusing to approve — ${granted.length} edge(s) were granted without a #proposed marker (vs ${baseRef})`);
-                listGrantedEdges(granted);
+            if (countGrants(granted) > 0) {
+                console.error(`Boundry: ✗ refusing to approve — ${countGrants(granted)} grant(s) were made without a #proposed marker (vs ${baseRef})`);
+                listGrants(granted);
                 process.exitCode = 1;
                 return;
             }

package/dist/core/model/boundary-model.d.ts

@@ -2,14 +2,25 @@
  * The single, source-agnostic representation everything in Boundry compiles
  * from. A visualizer adapter produces it; an enforcer adapter renders it.
  */
-/** A unit of architecture that maps to a folder of source code. */
+/** A unit of architecture that maps to a folder or a single file of source. */
 export interface Module {
     /** Stable id, taken from the diagram element. */
     id: string;
     /** Human-readable name for messages. */
     title: string;
-    /** Source path prefix the module owns, e.g. "src/core". */
-    folder: string;
+    /**
+     * Source path the module owns — a folder prefix (e.g. "src/core") or a single
+     * file (e.g. "src/ports/contract.ts"), per `kind`.
+     */
+    path: string;
+    /**
+     * Whether `path` is a folder (owns everything under it) or a single file
+     * (owns exactly that file). A file leaf lets a guarded contract or port sit
+     * beside its sibling sub-folders in a nested diagram, so its edges stay
+     * sibling-to-sibling — which is what keeps a deep C4 tree legal in LikeC4
+     * (ancestor↔descendant relationships are rejected) *and* enforceable.
+     */
+    kind: 'folder' | 'file';
 }
 /** A permitted dependency: modules in `from` may import modules in `to`. */
 export interface AllowedEdge {
@@ -19,6 +30,28 @@ export interface AllowedEdge {
 export interface BoundaryModel {
     modules: Module[];
     allowed: AllowedEdge[];
+    /**
+     * Ids of wildcard elements — diagram boxes tagged `#anything`. They map to no
+     * folder and are not modules; they stand for "the rest of the code". A module
+     * with an allowed edge to one is exempt from every boundary rule.
+     *
+     * This is the explicit way to say "deliberately unconstrained", for the
+     * composition root that must wire everything together. It is a drawn,
+     * reviewable grant — unlike opting out by staying unmapped, where the mere
+     * ABSENCE of a box would hand out the same power silently.
+     */
+    wildcards: string[];
+    /**
+     * Regex patterns for files that are analysed but never held to a boundary as
+     * an *importer*. Matched files are dropped from every rule's `from` side, so
+     * they may import anything; they are still governed as import *targets*.
+     *
+     * For test files and ambient `.d.ts` declarations: an integration test wiring
+     * real adapters across layers is doing its job, not breaking the
+     * architecture. From-side only — production importing a test helper stays as
+     * forbidden as it ever was.
+     */
+    exemptImporters: string[];
     /**
      * Optional code root declared fully governed. Every folder under it is
      * expected to be modelled, so importing territory no module claims is
@@ -27,6 +60,20 @@ export interface BoundaryModel {
      */
     governRoot?: string;
 }
+/**
+ * Modules holding an approved edge to a wildcard element, i.e. free to import
+ * anything. A `#proposed` edge to a wildcard is excluded from `allowed` like any
+ * other proposal, so the exemption only takes effect once a human approves it.
+ */
+export declare function unconstrainedModules(model: BoundaryModel): Set<string>;
+/**
+ * Exemption patterns present at `head` but not at `base`.
+ *
+ * An exemption is a grant — it lifts whole files out of every rule — so a new
+ * one has to face the same gate as a new edge. Without this, an agent blocked by
+ * a boundary could add `exemptImporters '/src/'` and walk straight through.
+ */
+export declare function newlyExemptedImporters(base: BoundaryModel, head: BoundaryModel): string[];
 /**
  * Edges allowed at `head` that were not allowed at `base`.
  *

package/dist/core/model/boundary-model.js

@@ -2,6 +2,26 @@
  * The single, source-agnostic representation everything in Boundry compiles
  * from. A visualizer adapter produces it; an enforcer adapter renders it.
  */
+/**
+ * Modules holding an approved edge to a wildcard element, i.e. free to import
+ * anything. A `#proposed` edge to a wildcard is excluded from `allowed` like any
+ * other proposal, so the exemption only takes effect once a human approves it.
+ */
+export function unconstrainedModules(model) {
+    const wildcards = new Set(model.wildcards);
+    return new Set(model.allowed.filter((edge) => wildcards.has(edge.to)).map((edge) => edge.from));
+}
+/**
+ * Exemption patterns present at `head` but not at `base`.
+ *
+ * An exemption is a grant — it lifts whole files out of every rule — so a new
+ * one has to face the same gate as a new edge. Without this, an agent blocked by
+ * a boundary could add `exemptImporters '/src/'` and walk straight through.
+ */
+export function newlyExemptedImporters(base, head) {
+    const exemptAtBase = new Set(base.exemptImporters);
+    return head.exemptImporters.filter((pattern) => !exemptAtBase.has(pattern));
+}
 const edgeKey = (edge) => `${edge.from} -> ${edge.to}`;
 /**
  * Edges allowed at `head` that were not allowed at `base`.

package/dist/core/pipeline/pipeline.d.ts

@@ -1,5 +1,18 @@
 import type { VisualizerPort, EnforcerPort, EnforcerConfig, CheckResult } from "../ports/ports.js";
 import type { AllowedEdge } from "../model/boundary-model.js";
+/**
+ * What a diagram grants that the approved base did not. Both kinds of grant are
+ * reported, because both let code cross a boundary that was previously closed.
+ *
+ * This lives with the pipeline rather than the ports: no driven port deals in
+ * it, it is what `verify` returns.
+ */
+export interface VerifyResult {
+    /** Dependencies added without going through a `#proposed` proposal. */
+    edges: AllowedEdge[];
+    /** Importer exemptions added, lifting files out of every rule. */
+    exemptions: string[];
+}
 /**
  * The SDK's public surface. Orchestrates the two driven ports and stays blind
  * to any concrete diagram source or linter — swap adapters, this is untouched.
@@ -13,11 +26,12 @@ export declare class Pipeline {
     /** Diagram -> boundary model -> run the linter over `sources`. */
     check(sources: string[]): Promise<CheckResult>;
     /**
-     * Edges this diagram grants that `base` did not — i.e. dependencies added
-     * without a `#proposed` marker. Proposals are excluded from the allow-list,
-     * so anything reported here bypassed the approval protocol.
+     * What this diagram grants that `base` did not — dependencies added without a
+     * `#proposed` marker, and importer exemptions added. Proposals are excluded
+     * from the allow-list, so anything reported here bypassed the approval
+     * protocol.
      */
-    verify(base: VisualizerPort): Promise<AllowedEdge[]>;
+    verify(base: VisualizerPort): Promise<VerifyResult>;
     /** Approve proposed edges: strip their `#proposed` markers from the diagram. */
     approve(): Promise<void>;
 }

package/dist/core/pipeline/pipeline.js

@@ -1,4 +1,4 @@
-import { newlyAllowedEdges } from "../model/boundary-model.js";
+import { newlyAllowedEdges, newlyExemptedImporters, } from "../model/boundary-model.js";
 /**
  * The SDK's public surface. Orchestrates the two driven ports and stays blind
  * to any concrete diagram source or linter — swap adapters, this is untouched.
@@ -21,13 +21,17 @@ export class Pipeline {
         return this.enforcer.check(model, sources);
     }
     /**
-     * Edges this diagram grants that `base` did not — i.e. dependencies added
-     * without a `#proposed` marker. Proposals are excluded from the allow-list,
-     * so anything reported here bypassed the approval protocol.
+     * What this diagram grants that `base` did not — dependencies added without a
+     * `#proposed` marker, and importer exemptions added. Proposals are excluded
+     * from the allow-list, so anything reported here bypassed the approval
+     * protocol.
      */
     async verify(base) {
         const [baseModel, headModel] = await Promise.all([base.read(), this.visualizer.read()]);
-        return newlyAllowedEdges(baseModel, headModel);
+        return {
+            edges: newlyAllowedEdges(baseModel, headModel),
+            exemptions: newlyExemptedImporters(baseModel, headModel),
+        };
     }
     /** Approve proposed edges: strip their `#proposed` markers from the diagram. */
     async approve() {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { BoundaryModel, Module, AllowedEdge, } from './core/model/boundary-model.js';
 export type { VisualizerPort, EnforcerPort, EnforcerConfig, CheckResult, Violation, } from './core/ports/ports.js';
-export { Pipeline } from './core/pipeline/pipeline.js';
+export { Pipeline, type VerifyResult } from './core/pipeline/pipeline.js';
 export { LikeC4Visualizer } from './adapters/visualizer/likec4.js';
 export { DepCruiserEnforcer } from './adapters/enforcer/depcruiser.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boundry",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Compile a C4 architecture diagram into a deterministic dependency linter. Deterministic architectural guardrails for AI agents and humans.",
   "type": "module",
   "license": "MIT",
@@ -39,6 +39,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -50,16 +51,16 @@
     "check": "tsx src/cli/index.ts check --arch arch src",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.json",
-    "test": "node --import tsx --test src/__tests__/e2e/*.e2e.test.ts",
+    "test": "node --import tsx --test \"src/__tests__/e2e/**/*.e2e.test.ts\"",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "dependency-cruiser": "^16.4.0",
-    "likec4": "^1.46.0"
+    "likec4": "^1.46.0",
+    "typescript": "^5.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.7.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.6.0"
+    "tsx": "^4.19.0"
   }
 }