octomap-python 1.8.0.post12__tar.gz → 1.8.0.13__tar.gz

octomap_python-1.8.0.13/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.14']
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install from source
+      run: uv sync --locked
+
+    - name: Ruff lint
+      run: uv run ruff check .
+
+    - name: Ruff format
+      run: uv run ruff format --check .
+
+    - name: Test
+      run: uv run pytest

octomap_python-1.8.0.13/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    uses: ./.github/workflows/wheels.yml
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/octomap-python
+    permissions:
+      id-token: write
+    steps:
+    - uses: actions/download-artifact@v4
+      with:
+        path: dist
+        merge-multiple: true
+
+    - uses: pypa/gh-action-pypi-publish@release/v1

octomap_python-1.8.0.13/.github/workflows/wheels.yml

@@ -0,0 +1,82 @@
+name: wheels
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  build_wheels:
+    name: Wheels (${{ matrix.os }} ${{ matrix.archs }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            archs: x86_64
+          - os: ubuntu-24.04-arm
+            archs: aarch64
+          - os: macos-14
+            archs: arm64
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Build wheels
+      uses: pypa/cibuildwheel@v4.1.0
+      env:
+        CIBW_ARCHS: ${{ matrix.archs }}
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: wheels-${{ matrix.os }}-${{ matrix.archs }}
+        path: wheelhouse/*.whl
+
+  build_sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Build sdist
+      run: pipx run build --sdist
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: sdist
+        path: dist/*.tar.gz
+
+  # Windows ships no wheel; prove the sdist builds from source there.
+  test_sdist_windows:
+    name: sdist from source (windows)
+    needs: build_sdist
+    runs-on: windows-latest
+    steps:
+    - uses: actions/download-artifact@v4
+      with:
+        name: sdist
+        path: dist
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.13'
+
+    - uses: actions/checkout@v4
+      with:
+        path: src
+
+    - name: Install from sdist
+      shell: bash
+      run: pip install --verbose dist/*.tar.gz
+
+    - name: Test
+      shell: bash
+      run: |
+        pip install pytest numpy
+        pytest src/tests/

octomap_python-1.8.0.13/.gitignore

@@ -0,0 +1,8 @@
+/_skbuild/
+/.venv/
+/MANIFEST
+
+/octomap/octomap.cpp
+/test/test1.bt
+
+/*.so

octomap_python-1.8.0.13/.python-version

@@ -0,0 +1 @@
+3.11

octomap_python-1.8.0.13/AGENTS.md

@@ -0,0 +1,13 @@
+## Agent skills
+
+### Issue tracker
+
+Issues are tracked in GitHub Issues via the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Canonical triage roles map 1:1 to GitHub label strings (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout: one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.

octomap_python-1.8.0.13/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [PEP 440](https://peps.python.org/pep-0440/): the first three
+segments track the bundled OctoMap C++ library version (currently 1.8.0), and a
+fourth segment counts binding revisions on that upstream.
+
+This history was backfilled from git and PyPI release records. Releases through
+1.8.0.post12 used a `.postN` suffix and predate git tags, so each is dated by its
+PyPI upload.
+
+## [1.8.0.13] - 2026-06-20
+
+The first release in over six years: a full build and tooling modernization plus
+several long-standing binding fixes.
+
+### Added
+- `dynamicEDT_getDistanceAndClosestObstacle` binding for the Euclidean distance transform (#37).
+
+### Fixed
+- `castRay` now fills the `end` coordinate whether or not the ray hits an occupied voxel (#36).
+- OctoMap file paths accept `str`, not only `bytes` (#38).
+- Iterator crash caused by the name-mangled `__is_end` / `__is_acceseable` attributes (#23).
+- Compilation on modern compilers, by pinning the OctoMap build to C++14 (#24).
+
+### Changed
+- Build migrated to scikit-build-core, producing a statically linked extension (#40).
+- OctoMap C++ is fetched and pinned via CMake FetchContent instead of a git submodule (#41).
+- Binary wheels (CPython 3.9-3.13; manylinux x86_64/aarch64, macOS arm64) and an sdist are built with cibuildwheel (#49).
+- PyPI publishing runs on GitHub Release via Trusted Publishing, with no stored API token (#52).
+- Adopted uv for the lockfile, dev dependency group, and install/CI flow (#42).
+- Migrated linting and formatting from black and flake8 to ruff (#46).
+- Test suite converted from unittest to pytest and run from the repository root (#43).
+- README rewritten with a Python quick start; relative image URLs are rewritten at build time via hatch-fancy-pypi-readme, retiring github2pypi (#44, #53).
+- Example dependencies moved from a published extra to a dependency group, with the GUI stack and Python pinned to keep them runnable (#42, #45).
+- CI tests the lower and upper supported Python bounds, 3.9 and 3.14 (#47).
+
+### Removed
+- Python 2 and Python 3.5 support, alongside repository housekeeping and an added LICENSE file (#35).
+
+## [1.8.0.post12] - 2019-07-03
+
+### Removed
+- `bbx_min` and `bbx_max` arguments from `extractPointCloud`.
+
+## [1.8.0.post11] - 2019-07-02
+
+### Fixed
+- Output dimension of `extractPointCloud`.
+
+## [1.8.0.post10] - 2019-06-29
+
+### Added
+- `bbx_min` and `bbx_max` arguments to `extractPointCloud`.
+
+## [1.8.0.post9] - 2019-06-21
+
+### Changed
+- Reverted linking against static libraries.
+
+### Removed
+- Unused `opengl_camera_transform`.
+
+## [1.8.0.post8] - 2019-06-21
+
+### Changed
+- Linked against static libraries.
+
+## [1.8.0.post7] - 2019-06-21
+
+### Fixed
+- Further handling of empty point clouds.
+
+## [1.8.0.post6] - 2019-06-21
+
+### Fixed
+- Zero-sized point cloud handling in `extractPointCloud`.
+
+## [1.8.0.post5] - 2019-06-11
+
+### Changed
+- Maintenance re-release; no functional changes.
+
+## [1.8.0.post4] - 2019-05-08
+
+### Added
+- `README.md` to the source distribution manifest.
+
+## [1.8.0.post3] - 2019-05-08
+
+### Added
+- `extractPointCloud`, plus visualization helpers and example scripts.
+
+### Changed
+- `getMetric*` methods return `numpy.ndarray`.
+
+## [1.8.0.post2] - 2019-04-16
+
+### Changed
+- README and `setup.py` packaging metadata.
+
+## [1.8.0.post1] - 2019-04-16
+
+### Added
+- Initial PyPI release of the OctoMap Python binding (bundling OctoMap 1.8.0):
+  OcTree read/write, node and tree iterators, `OcTreeKey`, ray casting, and a
+  dynamicEDT3D distance field.

octomap_python-1.8.0.13/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

octomap_python-1.8.0.13/CMakeLists.txt

@@ -0,0 +1,90 @@
+# find_package(Python ... Development.Module) needs CMake 3.18+.
+cmake_minimum_required(VERSION 3.18)
+project(octomap_python LANGUAGES CXX)
+
+# OctoMap targets an older C++ dialect; pin C++14 so its sources compile
+# cleanly (newer default standards make octomap's `byte` typedef clash with
+# std::byte).
+set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(
+  Python REQUIRED COMPONENTS Interpreter Development.Module NumPy)
+
+include(FetchContent)
+
+# OctoMap is fetched and pinned to a release tag rather than vendored as a git
+# submodule. Bumping the version is a one-line change to GIT_TAG.
+#
+# Pinned to v1.8.0 to match the package version line (octomap-python 1.8.0.N
+# bundles octomap 1.8.0).
+FetchContent_Declare(
+  octomap
+  GIT_REPOSITORY https://github.com/OctoMap/octomap.git
+  GIT_TAG v1.8.0
+  GIT_SHALLOW TRUE
+)
+# Populate the sources only; octomap's own CMake build is intentionally not run.
+# FetchContent_MakeAvailable() would add_subdirectory(octomap), which both
+# defines a CMake target named `octomap` (colliding with python_add_library
+# below) and pulls in octovis/Qt. Source-only population needs the low-level
+# FetchContent_Populate(), which CMake 3.30 deprecated; CMP0169 keeps that path
+# available (the POLICY guard leaves older CMake, which lacks it, untouched).
+if(POLICY CMP0169)
+  cmake_policy(SET CMP0169 OLD)
+endif()
+FetchContent_GetProperties(octomap)
+if(NOT octomap_POPULATED)
+  FetchContent_Populate(octomap)
+endif()
+
+set(octomap_dir "${octomap_SOURCE_DIR}")
+set(octomap_src "${octomap_dir}/octomap/src")
+set(edt_src "${octomap_dir}/dynamicEDT3D/src")
+
+# OctoMap, octomath and dynamicEDT3D are compiled straight into the extension
+# so the module is self-contained: no octomap shared libraries to resolve at
+# import time. octovis/Qt are simply never referenced here. The source lists
+# mirror octomap's own CMakeLists for the pinned release.
+set(octomap_sources
+  ${octomap_src}/AbstractOcTree.cpp
+  ${octomap_src}/AbstractOccupancyOcTree.cpp
+  ${octomap_src}/Pointcloud.cpp
+  ${octomap_src}/ScanGraph.cpp
+  ${octomap_src}/CountingOcTree.cpp
+  ${octomap_src}/OcTree.cpp
+  ${octomap_src}/OcTreeNode.cpp
+  ${octomap_src}/OcTreeStamped.cpp
+  ${octomap_src}/ColorOcTree.cpp
+  ${octomap_src}/math/Vector3.cpp
+  ${octomap_src}/math/Quaternion.cpp
+  ${octomap_src}/math/Pose6D.cpp
+  ${edt_src}/dynamicEDT3D.cpp
+  ${edt_src}/dynamicEDTOctomap.cpp
+)
+
+add_custom_command(
+  OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/octomap.cpp"
+  COMMAND Python::Interpreter -m cython --cplus -3
+          "${CMAKE_CURRENT_SOURCE_DIR}/octomap/octomap.pyx"
+          -o "${CMAKE_CURRENT_BINARY_DIR}/octomap.cpp"
+  DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/octomap/octomap.pyx"
+          "${CMAKE_CURRENT_SOURCE_DIR}/octomap/octomap_defs.pxd"
+          "${CMAKE_CURRENT_SOURCE_DIR}/octomap/dynamicEDT3D_defs.pxd"
+  COMMENT "Cythonizing octomap.pyx"
+  VERBATIM
+)
+
+python_add_library(octomap MODULE
+  "${CMAKE_CURRENT_BINARY_DIR}/octomap.cpp"
+  ${octomap_sources}
+  WITH_SOABI
+)
+target_include_directories(octomap PRIVATE
+  ${CMAKE_CURRENT_SOURCE_DIR}/octomap
+  ${octomap_dir}/octomap/include
+  ${octomap_dir}/dynamicEDT3D/include
+)
+target_link_libraries(octomap PRIVATE Python::NumPy)
+
+install(TARGETS octomap DESTINATION .)

octomap_python-1.8.0.13/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2013-2026, Kentaro Wada
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

octomap_python-1.8.0.13/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.2
+Name: octomap-python
+Version: 1.8.0.13
+Summary: Python binding of the OctoMap library.
+Maintainer-Email: Kentaro Wada <www.kentaro.wada@gmail.com>
+License: BSD-3-Clause
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Project-URL: Homepage, https://github.com/wkentaro/octomap-python
+Requires-Python: >=3.9
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# octomap-python
+
+[![PyPI](https://img.shields.io/pypi/v/octomap-python.svg)](https://pypi.org/project/octomap-python/)
+[![Python](https://img.shields.io/pypi/pyversions/octomap-python.svg)](https://pypi.org/project/octomap-python/)
+[![Build](https://github.com/wkentaro/octomap-python/actions/workflows/ci.yml/badge.svg)](https://github.com/wkentaro/octomap-python/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/octomap-python.svg)](https://pypi.org/project/octomap-python/)
+
+Python binding of [OctoMap](https://github.com/OctoMap/octomap), the 3D
+occupancy mapping library.
+
+OctoMap builds a probabilistic 3D occupancy map (an octree) from point clouds:
+you stream in sensor measurements and query whether any point in space is
+occupied, free, or still unknown. This package exposes that C++ library to
+Python with NumPy arrays as the interchange format, so point clouds and queries
+are plain `np.ndarray`s.
+
+<img src="https://raw.githubusercontent.com/wkentaro/octomap-python/main/examples/.readme/insertPointCloud.jpg" height="200px" />
+
+## Install
+
+```bash
+pip install octomap-python
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add octomap-python
+```
+
+Binary wheels are published for Linux (x86_64, aarch64) and macOS (Apple
+Silicon), CPython 3.9-3.13. Windows and other platforms build from the sdist
+and need a C++ compiler.
+
+## Quick start
+
+```python
+import numpy as np
+import octomap
+
+# Resolution is the smallest voxel edge length, in meters.
+octree = octomap.OcTree(0.1)
+
+# Insert a point cloud measured from a sensor at `origin`.
+points = np.random.uniform(-1, 1, size=(1000, 3))
+octree.insertPointCloud(
+    pointcloud=points,
+    origin=np.array([0.0, 0.0, 0.0]),
+)
+
+# Query a coordinate: occupied / free / unknown (never observed).
+node = octree.search(points[0])
+try:
+    print("occupied" if octree.isNodeOccupied(node) else "free")
+except octomap.NullPointerException:
+    print("unknown")
+
+# Bounding box of everything mapped so far.
+print(octree.getMetricMin(), octree.getMetricMax())
+
+# Persist to / restore from the OctoMap binary format.
+octree.writeBinary("tree.bt")
+restored = octomap.OcTree(0.1)
+restored.readBinary("tree.bt")
+```
+
+## Examples
+
+Runnable demos live in [`examples/`](examples); the teaser above is
+`insertPointCloud.py`:
+
+```bash
+git clone --recursive https://github.com/wkentaro/octomap-python.git
+cd octomap-python
+uv sync --group examples
+
+cd examples
+uv run python insertPointCloud.py
+```
+
+## Release
+
+Releases are published to PyPI by the `publish` workflow, which fires when a
+GitHub Release is published. It builds the wheel matrix + sdist and uploads via
+[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC, no
+stored token).
+
+To cut a release:
+
+1. Bump `version` in `pyproject.toml` to match the new tag and commit it.
+2. Create a GitHub Release with tag `vX.Y.Z` (e.g. `v1.8.0.13`).
+3. The `publish` workflow runs and uploads the built distributions to PyPI.
+
+## Acknowledgement
+
+This is a fork of
+[neka-nat/python-octomap](https://github.com/neka-nat/python-octomap).
+
+## License
+
+BSD-3-Clause ([LICENSE](https://github.com/wkentaro/octomap-python/blob/main/LICENSE))

octomap_python-1.8.0.13/README.md

@@ -0,0 +1,101 @@
+# octomap-python
+
+[![PyPI](https://img.shields.io/pypi/v/octomap-python.svg)](https://pypi.org/project/octomap-python/)
+[![Python](https://img.shields.io/pypi/pyversions/octomap-python.svg)](https://pypi.org/project/octomap-python/)
+[![Build](https://github.com/wkentaro/octomap-python/actions/workflows/ci.yml/badge.svg)](https://github.com/wkentaro/octomap-python/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/octomap-python.svg)](https://pypi.org/project/octomap-python/)
+
+Python binding of [OctoMap](https://github.com/OctoMap/octomap), the 3D
+occupancy mapping library.
+
+OctoMap builds a probabilistic 3D occupancy map (an octree) from point clouds:
+you stream in sensor measurements and query whether any point in space is
+occupied, free, or still unknown. This package exposes that C++ library to
+Python with NumPy arrays as the interchange format, so point clouds and queries
+are plain `np.ndarray`s.
+
+<img src="examples/.readme/insertPointCloud.jpg" height="200px" />
+
+## Install
+
+```bash
+pip install octomap-python
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add octomap-python
+```
+
+Binary wheels are published for Linux (x86_64, aarch64) and macOS (Apple
+Silicon), CPython 3.9-3.13. Windows and other platforms build from the sdist
+and need a C++ compiler.
+
+## Quick start
+
+```python
+import numpy as np
+import octomap
+
+# Resolution is the smallest voxel edge length, in meters.
+octree = octomap.OcTree(0.1)
+
+# Insert a point cloud measured from a sensor at `origin`.
+points = np.random.uniform(-1, 1, size=(1000, 3))
+octree.insertPointCloud(
+    pointcloud=points,
+    origin=np.array([0.0, 0.0, 0.0]),
+)
+
+# Query a coordinate: occupied / free / unknown (never observed).
+node = octree.search(points[0])
+try:
+    print("occupied" if octree.isNodeOccupied(node) else "free")
+except octomap.NullPointerException:
+    print("unknown")
+
+# Bounding box of everything mapped so far.
+print(octree.getMetricMin(), octree.getMetricMax())
+
+# Persist to / restore from the OctoMap binary format.
+octree.writeBinary("tree.bt")
+restored = octomap.OcTree(0.1)
+restored.readBinary("tree.bt")
+```
+
+## Examples
+
+Runnable demos live in [`examples/`](examples); the teaser above is
+`insertPointCloud.py`:
+
+```bash
+git clone --recursive https://github.com/wkentaro/octomap-python.git
+cd octomap-python
+uv sync --group examples
+
+cd examples
+uv run python insertPointCloud.py
+```
+
+## Release
+
+Releases are published to PyPI by the `publish` workflow, which fires when a
+GitHub Release is published. It builds the wheel matrix + sdist and uploads via
+[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC, no
+stored token).
+
+To cut a release:
+
+1. Bump `version` in `pyproject.toml` to match the new tag and commit it.
+2. Create a GitHub Release with tag `vX.Y.Z` (e.g. `v1.8.0.13`).
+3. The `publish` workflow runs and uploads the built distributions to PyPI.
+
+## Acknowledgement
+
+This is a fork of
+[neka-nat/python-octomap](https://github.com/neka-nat/python-octomap).
+
+## License
+
+BSD-3-Clause ([LICENSE](https://github.com/wkentaro/octomap-python/blob/main/LICENSE))

octomap_python-1.8.0.13/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_