boundry 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,13 +4,106 @@ 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
+## [0.5.0] — 2026-07-21
+
+### Fixed
+
+- **`approve` no longer leaves a stale, corrupted `boundry.diff.likec4`** ([#6]).
+  `approve` used to walk the derived diff file along with the model and splice the
+  marker tokens out of its *view rules* (`style element.tag = #proposed …`,
+  `include … where tag is #proposed`), mangling them into invalid LikeC4 — so
+  `likec4 validate` (and any `arch:verify` gate) went red immediately after a
+  successful approve, recoverable only by a separate `diff` run. `approve` now
+  skips the derived file and deletes it as part of enacting: the moment the last
+  proposal is approved those views are stale — they frame changes that are now
+  approved — so the post-approve workspace is clean and validates.
+
+### Added
+
+- **Per-altitude diff views** ([#7]). `boundry diff` now emits a focused view for
+  *every* layer that draws a changed edge, not only the common-ancestor layer. A
+  cross-system dependency between two deeply-nested leaves is drawable at each
+  endpoint's system and container as well as at the shared root; `diff` emits one
+  `view … of <scope>` for each, so a reviewer can open the change at whatever
+  altitude matters — the whole system, a specific container — instead of being
+  dropped at the noisy root view. The scopes are derived from how LikeC4's
+  `include *` actually renders: the common ancestor plus each endpoint's ancestor
+  chain down to its parent, never *above* the common ancestor (where both
+  endpoints collapse into one child and the edge becomes an undrawn self-loop) and
+  never the leaf endpoints themselves. Boxes are unchanged — one view at the box's
+  parent layer.
+
+### Changed
+
+- **`verify` now compares against the accepted `boundry.lock`, not a git ref.**
+  The lock was introduced in 0.4.0 to decouple *approved* from *committed*, but
+  `verify --base <ref>` kept re-deriving its baseline from a diagram at a git ref
+  — quietly re-coupling "accepted" to "committed", the very thing the lock exists
+  to break. `verify` now reads the lock, exactly as `annotate` does, so the two
+  share one baseline and can never disagree about what "accepted" means. It also
+  catches a committed-but-*unapproved* bare edge, which the git-ref baseline
+  silently absorbed. The `--base` flag is gone from `verify` and `approve`;
+  `approve`'s anti-laundering pre-check now runs the same lock-based gate, and the
+  first `approve` (no lock yet) bootstraps the initial accepted state. **Tradeoff,
+  by design:** the baseline is the working-tree lock, so the gate leans on
+  `approve` being a human act — the lock moves only when someone approves, which
+  is why the skill forbids agents from running it.
+
+[#6]: https://github.com/makspiechota/boundry/issues/6
+[#7]: https://github.com/makspiechota/boundry/issues/7
+
+## [0.4.0] — 2026-07-17
 
 Makes the "one file can be both the communication diagram and the enforcement
-model" promise hold for deep, nested C4 trees.
+model" promise hold for deep, nested C4 trees, and makes a proposed change
+highlight itself — deterministically, on every LikeC4 surface.
 
 ### Added
 
+- **Accepted-state lock + `annotate` (prototype).** `approve` now records the
+  accepted model to `boundry.lock` beside the diagram — a baseline Boundry
+  **owns**, rather than inferring it from whatever git happens to hold, so
+  "approved" is decoupled from "committed". `boundry annotate` diffs the diagram
+  against that lock and rewrites every undeclared addition — a bare new edge (a
+  self-grant) or box — into an explicit `#proposed` proposal in the source,
+  deterministically and idempotently. Turns silent drift into a reviewable,
+  colourable proposal. (Additive only; deletions are reported, not round-tripped
+  back into the DSL — re-materialising a removed box would resurrect it as an
+  enforced module.)
+  - **Cross-surface highlighting** ([#5]). `annotate` also paints each marker with
+    an intrinsic `style { color amber }` (`#proposed`) / `style { color red }`
+    (`#proposal-delete`) on the element itself. Intrinsic style is the only styling
+    LikeC4 renders on **every** surface — base views *and* the "relationships of X"
+    panel — so a proposal is highlighted wherever a reviewer looks, not just inside
+    the diff views (whose view-scoped rules stop at the view boundary). Idempotent,
+    and `approve` strips the styling back out with the marker: a `#proposed` edge
+    returns to bare, a `#proposed` box loses its colour, a `#proposal-delete` is
+    removed outright. Needs LikeC4 ≥ 1.58 to render.
+- **Per-layer diff views — `boundry diff` (prototype).** Generates a focused
+  LikeC4 view for every layer that holds a pending change — an edge or box tagged
+  `#proposed` or `#proposal-delete` — scoped to the tightest element that draws
+  it, into a derived `boundry.diff.likec4`. This matters because a proposal nested
+  inside a box is invisible once that box collapses at a wider zoom, so a single
+  all-up view hides it; one view per layer surfaces every change in the scope
+  where it renders. It reads the diagram's own markers, not the lock, so it frames
+  whatever `annotate` or a human marked. The file is derived — overwritten each
+  run, removed when nothing is proposed — so it always reflects the current
+  diagram; regenerate after `approve`.
+  - **Deterministic highlighting** ([#4]). `diff` emits the LikeC4 style rules
+    into the derived file, so a `#proposed` box fills amber and its edge goes
+    amber + solid, a `#proposal-delete` red — with no hand-styling. Boxes are
+    styled in place (`style element.tag`, never force-included), so a nested
+    proposal stays in its layer; the rules live only in the generated views, so
+    user-authored views are untouched. Rules are emitted only for marker tags
+    actually in use (referencing an undeclared tag is a hard LikeC4 error).
+- **`#proposal-delete` — the deletion half of the approval lifecycle.** Tag an
+  edge or a box `#proposal-delete` to propose retiring it. The marker colours it
+  red; a pending deletion changes nothing (the edge stays allowed, the box stays
+  enforced), so proposing a removal never breaks the build. On `approve`, the
+  marked edge or box is removed from the diagram outright — deterministically, by
+  splicing the LikeC4 CST — where `#proposed` only strips its own marker and
+  leaves the edge behind. `#proposed` (amber, additive) and `#proposal-delete`
+  (red, subtractive) are now the two halves of every change.
 - **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
@@ -26,8 +119,19 @@ model" promise hold for deep, nested C4 trees.
 
 - **`Module.folder: string` → `Module.path: string` + `Module.kind: 'folder' | 'file'`.**
   SDK-breaking; the diagram surface and CLI are unaffected.
+- **`likec4` floor raised to `^1.58.0`.** The diff-view style-rule syntax Boundry
+  emits is verified against LikeC4 1.58; rendering the coloured views needs a
+  renderer at least that new.
 
 [#3]: https://github.com/makspiechota/boundry/issues/3
+[#4]: https://github.com/makspiechota/boundry/issues/4
+[#5]: https://github.com/makspiechota/boundry/issues/5
+
+## [0.3.0] — 2026-07-16 — superseded by 0.4.0
+
+Published early from a pre-feature snapshot (≈ 0.2.0 plus the `#anything`
+wildcard) and never carried the work now listed under 0.4.0. npm versions are
+immutable, so it stays on the registry; use **0.4.0**.
 
 ## [0.2.0] — 2026-07-16
 

package/README.md

@@ -227,27 +227,120 @@ 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
+boundry verify  --arch arch   # any edge granted without a marker, vs the lock?
+boundry approve --arch arch   # HUMAN ONLY: strip markers = approve, update the lock
 ```
 
-`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.
+`verify` compares the working diagram against the accepted **`boundry.lock`** 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` runs the same gate first, so
+it won't launder a self-granted edge into an approved one; then it enacts the
+proposals and records the new accepted state to the lock.
+
+The baseline is the lock, not a git ref: it's the state Boundry *owns*, so
+"accepted" never collapses into merely "committed". (One consequence, by design:
+the gate leans on `approve` being a human act — the lock moves only when someone
+approves. That's why the skill forbids agents from running it.)
+
+**To retire an edge or a box, propose its removal** with `#proposal-delete`
+instead of deleting it. The marker colours it red; a pending deletion changes
+nothing (the edge stays allowed, the box stays enforced) so it never breaks the
+build. Then `approve` removes the marked edge or box outright:
+
+```likec4
+  module legacy 'Legacy' {
+    #proposal-delete
+    metadata { folder 'src/legacy' }
+  }
+  api -> legacy #proposal-delete
+```
+
+So `#proposed` and `#proposal-delete` are the two halves of a change — an amber
+addition that `approve` makes permanent, and a red removal that `approve` takes
+away — each a visible mark on the diagram until a human acts.
 
 Point your agents at
 [`.claude/skills/define-architecture-boundaries`](.claude/skills/define-architecture-boundaries/SKILL.md)
 and they'll follow this protocol.
 
+### Catching drift — `annotate` (prototype)
+
+`verify` catches a self-grant and fails; `annotate` is the other half — it
+*rewrites* the same drift into a reviewable proposal. Both read the same baseline,
+the accepted **`boundry.lock`** that `approve` records beside the diagram, so they
+can never disagree about what "accepted" means.
+
+```bash
+boundry approve  --arch arch          # enact proposals AND write boundry.lock
+boundry annotate --arch arch          # rewrite undeclared additions as #proposed
+```
+
+`annotate` finds every edge or box that drifted past the lock without a marker —
+a self-grant — and rewrites it in place as a `#proposed` proposal. That's not
+cosmetic: a `#proposed` edge leaves the allow-list, so the silent grant becomes a
+red-again check and a highlighted box on the diagram, awaiting a real approval. It
+handles additions only; a removal is reported, not re-drawn (re-adding a deleted
+box would resurrect it as an enforced module).
+
+It also **paints the markers** — every `#proposed` edge/box gets an intrinsic
+`style { color amber }`, every `#proposal-delete` a `style { color red }`, written
+onto the element itself. Intrinsic style is the one styling LikeC4 renders on
+*every* surface — base views **and the "relationships of X" panel** — so a
+proposal shows up highlighted wherever a reviewer looks, not only in the generated
+diff views (whose view-scoped rules stop at the view boundary). `approve` strips
+this styling back out with the marker: a `#proposed` edge returns to bare, a
+`#proposed` box stays but loses its colour, a `#proposal-delete` is removed
+outright. Requires **LikeC4 ≥ 1.58** to render.
+
+### Reviewing a proposal — per-layer diff views (prototype)
+
+A proposal nested inside a box is invisible at a wider zoom: at the top level the
+box collapses and its inner `#proposed` edge disappears. So `diff` generates a
+**focused view for every layer that draws a pending change** — into a derived
+`boundry.diff.likec4`:
+
+```bash
+boundry diff --arch arch              # (re)write boundry.diff.likec4
+likec4 serve arch                     # review each layer, changes coloured
+```
+
+The highlighting is **generated, not hand-styled** — `diff` emits the LikeC4
+style rules into the derived file, so every `#proposed` box fills amber and edge
+goes amber + solid, every `#proposal-delete` red, deterministically. That closes
+the last manual seam: `annotate` marks, `diff` colours, no agent-dependent
+styling step. Boxes are styled *in place* (never force-included), so a nested
+proposal stays in its own layer; unchanged elements keep their defaults; and the
+rules live only in the generated views, so your own views are untouched.
+
+A changed edge is drawn at **every altitude it appears**, not only the
+common-ancestor layer — so a cross-system dependency between two deeply-nested
+leaves gets a view at each endpoint's system and container as well as at the
+shared root. Open the change at whatever altitude matters (the whole system, a
+specific container) instead of being dropped at the noisy root view. `diff` emits
+only the layers that genuinely draw the edge: never above the common ancestor
+(where it collapses to an undrawn self-loop), never the leaf endpoints themselves.
+
+The file is a **derived artifact**: overwritten every run, removed when nothing is
+proposed, so it always matches the current diagram. `approve` deletes it too, as
+part of enacting — the moment the last proposal is approved the views are stale,
+so the post-approve workspace validates clean. It reads the diagram's own markers
+(not the lock), so it frames whatever `annotate` or a human has marked. Being
+derived, it's a `.gitignore` candidate (`boundry.diff.likec4`).
+
+> Rendering the coloured diff views needs **LikeC4 ≥ 1.58** (the style-rule syntax
+> Boundry emits). Boundry itself depends on that floor; the tool you review with
+> (`likec4 serve`, the CLI, or the IDE extension) has to meet it too.
+
 ## 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>]
+boundry verify   [--arch <dir>] [--cwd <dir>]
+boundry approve  [--arch <dir>] [--cwd <dir>]
+boundry annotate [--arch <dir>]
+boundry diff     [--arch <dir>]
 ```
 
 | Flag | Meaning |
@@ -255,14 +348,20 @@ boundry approve  [--arch <dir>] [--cwd <dir>] [--base <git-ref>]
 | `--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.
+- **`verify`** rejects dependencies granted without a proposal, comparing the
+  diagram against the accepted `boundry.lock`. Needs a lock — run `approve` once
+  to record one.
+- **`approve`** runs the same gate, then enacts markers (strips `#proposed`,
+  removes `#proposal-delete`) and writes `boundry.lock`. For humans, not agents.
+- **`annotate`** rewrites undeclared additions as `#proposed`, diffing against
+  `boundry.lock`.
+- **`diff`** generates a focused, colour-coded review view per layer that holds a
+  pending change, into a derived `boundry.diff.likec4`.
 
 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
@@ -283,9 +382,8 @@ 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'
+      # Reject any dependency granted without a proposal, vs the committed lock.
+      - run: npx boundry verify --arch arch
 ```
 
 ## Programmatic use (SDK)

package/dist/adapters/visualizer/likec4.d.ts

@@ -1,5 +1,5 @@
-import type { VisualizerPort } from '../../core/ports/ports.js';
-import type { BoundaryModel } from '../../core/model/boundary-model.js';
+import type { VisualizerPort, DiffView } from '../../core/ports/ports.js';
+import type { BoundaryModel, AllowedEdge } from '../../core/model/boundary-model.js';
 /**
  * First visualizer adapter. Reads a LikeC4 workspace and lifts it into the
  * boundary model: any element carrying a `folder` metadata key becomes a
@@ -11,10 +11,49 @@ export declare class LikeC4Visualizer implements VisualizerPort {
     constructor(workspaceDir: string);
     read(): Promise<BoundaryModel>;
     /**
-     * Deterministically strip `#proposed` markers from the diagram source,
-     * promoting intent edges to approved. Source-preserving; never an LLM edit —
-     * it locates each marked relationship in the LikeC4 CST and splices out its
-     * proposal decoration, leaving all other formatting intact.
+     * Deterministically enact a diagram's pending proposals. Source-preserving,
+     * never an LLM edit — it walks the LikeC4 CST and splices ranges directly:
+     *   - `#proposed` markers are stripped, promoting their intent edges to
+     *     approved (the edge/box stays, permanently allowed);
+     *   - `#proposal-delete` markers take their whole edge or box with them, so
+     *     approving a proposed removal actually removes it.
+     * All other formatting is left intact.
+     *
+     * The derived `boundry.diff.likec4` is skipped, not approved: it holds no real
+     * markers, only view rules that *reference* the marker tags (`style element.tag
+     * = #proposed`, `include … where tag is #proposed`). Splicing those `#proposed`
+     * tokens out would corrupt the rules into invalid LikeC4. And it is stale the
+     * moment the last proposal is enacted — it describes changes that are now
+     * approved — so approve deletes it, leaving a workspace `likec4 validate` accepts.
      */
     approve(): Promise<void>;
+    /**
+     * Deterministically mark the given edges and elements `#proposed`. The inverse
+     * of `approve` for additions: an undeclared new edge (a self-grant) or box is
+     * rewritten into an explicit, colourable proposal. It locates each target's
+     * relation/element in the CST by its resolved ids and injects the marker,
+     * skipping anything already marked, so it is idempotent.
+     */
+    propose(edges: AllowedEdge[], moduleIds: string[]): Promise<void>;
+    /**
+     * Paint intrinsic style on every marked edge and box, so a proposal is
+     * highlighted on *every* LikeC4 surface — base views and the "relationships of
+     * X" panel, not just the generated diff views (which only carry view-scoped
+     * rules). A `#proposed` edge/box gets `style { color amber }`, a
+     * `#proposal-delete` `style { color red }`. Source-preserving and idempotent —
+     * anything already carrying the canonical style is left alone. `approve` strips
+     * this styling back out when it enacts the marker.
+     */
+    styleMarkers(): Promise<void>;
+    /**
+     * Generate a focused diff view for every layer that holds a pending change.
+     * Walks the diagram's own `#proposed` / `#proposal-delete` markers (never the
+     * lock — a `#proposal-delete` has no lock delta) and writes one `view … of
+     * <scope>` per layer to a derived `boundry.diff.likec4`. A box is bucketed into
+     * its parent layer; an edge into *every* layer that draws it (see `edgeScopes`),
+     * so a cross-system dependency can be reviewed at each altitude, not only the
+     * common-ancestor layer. The file is overwritten each run and removed when
+     * nothing is proposed, so it always reflects the current diagram.
+     */
+    emitDiffViews(): Promise<DiffView[]>;
 }