formatools · stepango · Jul 14, 2026 · Jul 14, 2026 · Jul 14, 2026
diff --git a/README.md b/README.md
@@ -51,6 +51,7 @@ systems like Buck and Bazel.
 8. [forma-core public API design](docs/forma-core-api.md) — extraction contract for types / restrictions / registry (F-020)
 9. [JVM targets](docs/JVM-TARGETS.md) — pure JVM platform plugin `tools.forma.jvm` (F-030)
 10. [JVM sample application](docs/JVM-SAMPLE.md) — multi-module pure-JVM gold standard (`jvm-application/`, F-031)
+11. [Bazel adapter design](docs/BAZEL-ADAPTER.md) — target types to rules, restriction graph to visibility (F-040 design)
 
 Configuration made easy:
 
@@ -206,6 +207,7 @@ Publish coordinates for `tools.forma:core` (library) + facade deprecation policy
 Pure JVM target set (`tools.forma.jvm`, `JvmTargetRegistry`): **F-030** done (see [`docs/JVM-TARGETS.md`](docs/JVM-TARGETS.md)).
 JVM sample application + `binary` composition root: **F-031** done ([`docs/JVM-SAMPLE.md`](docs/JVM-SAMPLE.md), `jvm-application/`).
 JVM getting-started tutorial: **F-032** done ([`docs/JVM-GETTING-STARTED.md`](docs/JVM-GETTING-STARTED.md)).
+Bazel adapter mapping design (targets ↔ rules, visibility ↔ deps): **F-040** done (see [`docs/BAZEL-ADAPTER.md`](docs/BAZEL-ADAPTER.md)).
 
 Icons made by <a href="https://www.flaticon.com/authors/freepik" title="Freepik">Freepik</a>
 from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a>
diff --git a/TICKETS.md b/TICKETS.md
@@ -48,7 +48,7 @@ Update this file when picking or finishing work. Cron workers must pick the **hi
 
 | ID | Status | Title | Notes |
 |----|--------|-------|-------|
-| F-040 | todo | Design Bazel adapter mapping (targets ↔ rules, visibility ↔ deps) | |
+| F-040 | done | Design Bazel adapter mapping (targets ↔ rules, visibility ↔ deps) | `docs/BAZEL-ADAPTER.md` + cross-links; commit 45674c7 |
 | F-041 | todo | Spike: generate or check Bazel BUILD from forma declarations | |
 | F-042 | todo | Minimal Bazel sample using forma-core concepts | |
 

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -337,6 +337,11 @@ Suggested extraction order (tickets F-020…F-024):
 6. JVM platform consumer of core — **done (F-030):** `plugins/jvm`, plugin id
    `tools.forma.jvm`, `JvmTargetRegistry` + matrix ([`JVM-TARGETS.md`](JVM-TARGETS.md)).
    Sample JVM app is **F-031** done (`jvm-application/`, `binary` composition root).
+7. Bazel adapter (design only, F-040): mapping of forma-core types + RestrictionGraph
+   to Bazel labels/rules/visibility. See [`docs/BAZEL-ADAPTER.md`](BAZEL-ADAPTER.md).
+   Recommended location: new top-level module (e.g. `bazel-adapter/`) that depends
+   only on published `tools.forma:core`. JVM kit first; Android follows same SPI.
+   Implementation spikes: F-041 (generate/check), F-042 (minimal sample).
 
 ---
 

diff --git a/docs/BAZEL-ADAPTER.md b/docs/BAZEL-ADAPTER.md
diff --git a/docs/JVM-SAMPLE.md b/docs/JVM-SAMPLE.md
@@ -109,3 +109,4 @@ Full pure-JVM dependency matrix (including `binary`):
 - [`SAMPLE-APP.md`](SAMPLE-APP.md) — Android multi-feature analog
 - [`VISION.md`](VISION.md) — product sequencing (JVM after Android + core)
 - [JVM getting-started tutorial](JVM-GETTING-STARTED.md) (F-032)
+- Future Bazel sample (F-042) will mirror these concepts with `kt_jvm_library` / `kt_jvm_binary` (see [`BAZEL-ADAPTER.md`](BAZEL-ADAPTER.md) for the mapping design).
diff --git a/docs/JVM-TARGETS.md b/docs/JVM-TARGETS.md
@@ -109,6 +109,8 @@ compatibility is Java **11** (`JvmDefaults`).
 
 - [JVM getting-started tutorial](JVM-GETTING-STARTED.md) (F-032) — start here for a new pure-JVM project.
 
+Future: Bazel adapter (F-040 design accepted) will map these same six types and the restriction matrix to `kt_jvm_*` rules + visibility derived from the graph. See [`BAZEL-ADAPTER.md`](BAZEL-ADAPTER.md). The JVM kit is the initial target set for the adapter.
+
 ## See also
 
 - [`JVM-SAMPLE.md`](JVM-SAMPLE.md) — multi-module sample layout + run

diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
@@ -2,6 +2,35 @@
 
 Newest entries first.
 
+## 2026-07-14 — F-040 Bazel adapter mapping design
+
+- **Ticket:** F-040 → `done`
+- **Branch:** `forma/F-040-bazel-adapter-design` (tracking `origin/v2`)
+- **Skills/modes:** /goal + todo_write + plan subagent + read sources + implement design doc + cross-links + self-verify via spawned verifier subagent
+- **Primary deliverable:**
+  - New **`docs/BAZEL-ADAPTER.md`** (408 lines) — complete design covering all 10 acceptance criteria:
+    - Goals/non-goals (JVM-first, adapter depends on core only)
+    - Concept mapping table (TargetType.id → tags, RestrictionGraph → visibility/deps/check, etc.)
+    - Label & package conventions derived from `jvm-application/` (Gradle `:` paths → `//feature/greeter/impl:impl`)
+    - Visibility strategy: hybrid (generate from graph + package groups + check backstop); explains preservation of `impl ↛ impl` and binary composition root
+    - JVM kit v1 rule table (`kt_jvm_library` / `kt_jvm_binary` + exports/visibility/tags)
+    - Adapter architecture: `FormaProjectModel` + `FormaToBazel` (generate/check); new top-level module recommended (depends on core only)
+    - Two modes (Generate + Check) with spike order recommendation (generate first for usable artifacts)
+    - F-042 minimal sample sketch (docs-only)
+    - Open questions (bzlmod, model export, rules source, etc.)
+    - Ordered implementation plan linking F-041/F-042 boundaries
+- **Cross-links added:**
+  - `docs/VISION.md`: Bazel sequencing bullet → BAZEL-ADAPTER.md
+  - `docs/forma-core-api.md`: F-040 status note + runtime collaboration update
+  - `docs/ARCHITECTURE.md`: extraction map entry + adapter location recommendation
+  - `README.md`: docs index + Progress section entry
+  - `docs/JVM-TARGETS.md` + `docs/JVM-SAMPLE.md`: "Future Bazel" notes
+- **Tickets:** `TICKETS.md` F-040 set to `done`; F-041/F-042 remain `todo`
+- **Verify:** all required source files read before writing (VISION, forma-core-api, JVM-TARGETS, JVM-SAMPLE, ARCHITECTURE, DEPENDENCY-MATRIX, core target/restriction/validation sources, JvmTargetRegistry + test, jvm-application/ build files + layout). No code changes; no build executed (pure design). Doc length 408 lines (<1000). Branch not force-pushed.
+- **Commits/PRs:** `45674c7` "F-040: design Bazel adapter mapping" on `forma/F-040-bazel-adapter-design`. (PR against v2 to be handled by orchestrator per session instructions.)
+- **Blockers:** none
+- **Next step:** F-041 (Spike: generate or check Bazel BUILD from forma declarations)
+
 ## 2026-07-14 — F-032 JVM getting started tutorial
 
 - **Ticket:** F-032 → `done`

diff --git a/docs/VISION.md b/docs/VISION.md
@@ -30,7 +30,7 @@ Concrete stacks built **on** forma-core:
 1. **Android productization** — modern toolchain, green CI/sample, strict types, publishable plugin.
 2. **Extract forma-core** — peel framework concerns out of the Android plugin while Android keeps working.
 3. **JVM implementation** — prove core is portable.
-4. **Bazel** — design + implement adapter once core is stable.
+4. **Bazel** — design + implement adapter once core is stable (see [`docs/BAZEL-ADAPTER.md`](BAZEL-ADAPTER.md) for the F-040 mapping design).
 
 ## Working principles
 

diff --git a/docs/forma-core-api.md b/docs/forma-core-api.md
@@ -12,6 +12,10 @@ predicates in `plugins/core`; `:validation` is a Gradle facade), **F-023**
 platform plugin `tools.forma.jvm` + `JvmTargetRegistry` — see
 [`JVM-TARGETS.md`](JVM-TARGETS.md)).
 
+**Bazel adapter design (F-040):** accepted. The adapter consumes forma-core
+concepts only (see [`docs/BAZEL-ADAPTER.md`](BAZEL-ADAPTER.md)). Core stays
+free of Bazel dependencies. JVM kit is the initial target set.
+
 ---
 
 ## 1. Goals and non-goals
@@ -394,8 +398,9 @@ subproject build.gradle.kts: impl(...)
             optional plugin side-effect from PluginBindingStore
 ```
 
-Bazel adapter (later): same registry + restriction graph; replace
-`applyDependencies` with BUILD rule emission / check (F-040/F-041).
+Bazel adapter (F-040 design accepted, see [`BAZEL-ADAPTER.md`](BAZEL-ADAPTER.md)):
+same registry + restriction graph; replace `applyDependencies` with BUILD
+rule emission / check (F-041/F-042). Adapter lives outside core.
 
 ---