roadmap-core 0.1.0__tar.gz

roadmap_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 roadmap-core contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

roadmap_core-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: roadmap-core
+Version: 0.1.0
+Summary: The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend.
+License: MIT
+Project-URL: Source, https://github.com/gald33/lucille/tree/main/roadmap-core
+Keywords: roadmap,backlog,dependency-graph,agents,planning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: files
+Requires-Dist: pyyaml>=6; extra == "files"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# roadmap-core
+
+The roadmap graph: status derivation, dependency and relation edges, arc state,
+validation, and the markdown renderers behind `roadmap/ROADMAP.md` and `ARCS.md`.
+
+**Stdlib-only and dependency-free**, which is the point rather than a nicety.
+Three properties depend on it:
+
+1. `scripts/roadmap.py` loads `roadmap_core/graph.py` **by path**, so a coding
+   agent in a checkout can read the backlog with no install, no DB, no admin
+   token and no network.
+2. The Lucille backend imports the same module, so a status derived by the API
+   and a status rendered into the committed markdown cannot disagree — one
+   implementation, two callers. That divergence is a failure this repo has been
+   bitten by before.
+3. It is the extraction seam. The roadmap is being prepared to run as its own
+   product whose default store is a single SQLite file with nothing to
+   provision; a package that pulled in a web framework or an ORM could not be
+   adopted by another repo without adopting Lucille with it.
+
+## Storage
+
+`store.py` is the schema — one SQLite file, `CREATE TABLE IF NOT EXISTS` on first
+open, no migration step. `stores.py` is what you talk to:
+
+| | `LocalStore` | `ApiStore` |
+|---|---|---|
+| needs | a writable path | a `call(method, path, payload)` |
+| provisioning | none | a running host |
+| `claim`/`release` | one `BEGIN IMMEDIATE` transaction | one HTTP request |
+| `impact` | raises `Unsupported` | the host's tickets |
+
+Both satisfy the same `Store` protocol, so a caller never branches on which it
+holds. `ApiStore` is constructed with the host's own caller and holds no token,
+no URL and no `urllib` import — auth stays entirely a host concern, and
+`test_stores.py` asserts that rather than trusting it.
+
+```python
+from roadmap_core.stores import LocalStore
+
+with LocalStore("roadmap/roadmap.db") as store:   # created if absent
+    store.upsert_item({"key": "a-thing", "title": "A thing"})
+    store.claim("a-thing", by="claude/some-branch")
+```
+
+From the CLI, `--source local` on `push`, `claim`, `release` and `status`, or
+`ROADMAP_SOURCE=local` once. `ROADMAP_STORE` sets the path.
+
+## Adopting it in another project
+
+Measured end to end by `tests/test_adoption.py`, which runs the CLI as a
+subprocess against a scratch project with nothing on the path but this package
+— no backend, no FastAPI, no SQLAlchemy, no Postgres, no server, no token.
+
+```bash
+pip install "roadmap-core[files]"   # [files] adds PyYAML, which authoring needs
+mkdir -p roadmap/items
+export ROADMAP_SOURCE=local
+```
+
+That is the whole install. `roadmap` is a console script that comes with the
+package — there is nothing to copy. (It used to say `curl -o scripts/roadmap.py
+<this repo>/scripts/roadmap.py`, and this repo is private, so the package was
+installable, importable and useless to anyone outside it.)
+
+Then the ordinary loop, which needs nothing else:
+
+```bash
+cat > roadmap/items/first-thing.yaml <<'YAML'
+id: first-thing
+title: The first thing to do
+status: ready
+evidence: |
+  Why this is worth doing, and how you will know it worked.
+YAML
+
+roadmap push            # files -> store
+roadmap ready           # what is startable
+roadmap claim first-thing
+roadmap release first-thing
+```
+
+The store is one SQLite file at `roadmap/roadmap.db`. There is nothing to
+provision and no migration to run: it is created on first open.
+
+**Two things that are conventions rather than choices**, both found by doing
+this rather than by reading the code:
+
+- **Your project root is the nearest ancestor holding `roadmap/items` or
+  `.git`**, so the commands work from anywhere inside it. Set
+  `ROADMAP_REPO_ROOT` to pin it. Deliberately not bare `roadmap/`: that is a
+  directory the tool *creates*, so keying on it let one command run in the
+  wrong place mint the marker that made that place look like a project
+  forever after.
+- **Authoring is writing a YAML file**, not calling an API. `push` is what
+  moves it into the store; there is no `roadmap new`. That is deliberate:
+  filing an item belongs in a diff somebody reviews.
+
+`ROADMAP_SOURCE=local` selects the SQLite store. Without it the CLI expects the
+API store, which is how Lucille runs it — see `roadmap_core.stores`.
+
+### CI
+
+Copy `templates/roadmap.yml` to `.github/workflows/roadmap.yml`. That is the
+whole CI story for the floor:
+
+```
+push      # files -> store, rebuilt fresh each run
+validate  # schema, dangling dependencies, cycles
+sync --check   # is the committed ROADMAP.md still what the graph renders?
+```
+
+No schedule, no credentials, no bot identity, no commit back to the default
+branch, no self-hosted runner. `tests/test_adoption.py` reads the commands out
+of that file and runs them, so a template that has drifted from the CLI fails
+rather than reading as tested.
+
+The third line is the one that earns the workflow. `ROADMAP.md` is generated but
+committed — that is what lets an agent read the backlog with no install and no
+network — and a generated file nobody regenerates is a file that lies.
+
+**Do not commit `roadmap/roadmap.db`.** It is derived: `push` rebuilds it from
+the YAML on first open, and a binary file in git conflicts on every claim. The
+files are the record; the store is the transaction that decides who gets one.
+
+### Upgrading to a served store
+
+The floor's simplicity comes from one property: the store is inside the
+checkout, so there is no second copy to drift from. Move the store to a server —
+so that claims are visible across machines the moment they are taken, rather
+than when a branch merges — and four things come back, none of which the
+template can supply for you:
+
+| What returns | Why |
+|---|---|
+| A **credential** step | the store is now behind auth, and the CLI needs a token per run |
+| A **wait-for-reachable** step | a concurrent deploy can hold the store down, and being early is not being wrong |
+| `pull` and a **bot commit** | the store now knows things no checkout does, and they have to land in the files an agent reads |
+| A **schedule** | finishing an item is usually a code change somewhere else entirely, so no path filter can catch it — only re-asking on a clock can |
+
+`ApiStore` is constructed with your own caller, so the auth stays yours (see the
+table under [Storage](#storage)). Lucille's `.github/workflows/roadmap-sync.yml`
+is the worked example of all four, and the reason it is not shipped as a
+template: almost every line of it is a consequence of Lucille's own deployment,
+and handing an adopter that machinery for a problem they do not have reads as
+required rather than as one option.
+
+## What is NOT here
+
+HTTP, auth, and the CLI. The graph is pure functions over plain dicts keyed by
+`key`, so the same code serves DB rows, API payloads and parsed YAML with no
+adapter. Lucille's own persistence stays in `backend/app/crud/roadmap.py` over
+SQLAlchemy; the two definitions of the same three tables are held together by
+`backend/tests/test_roadmap_store_parity.py`, which asserts both the columns and
+the row dicts the two readers produce.
+
+The package's tests live in `tests/` here and import nothing outside the stdlib.
+`.github/workflows/roadmap-core-tests.yml` runs them in a job that fails if
+`app`, `fastapi`, `sqlalchemy` or `yaml` can be imported at all — the isolation
+is asserted, not assumed.

roadmap_core-0.1.0/README.md

@@ -0,0 +1,160 @@
+# roadmap-core
+
+The roadmap graph: status derivation, dependency and relation edges, arc state,
+validation, and the markdown renderers behind `roadmap/ROADMAP.md` and `ARCS.md`.
+
+**Stdlib-only and dependency-free**, which is the point rather than a nicety.
+Three properties depend on it:
+
+1. `scripts/roadmap.py` loads `roadmap_core/graph.py` **by path**, so a coding
+   agent in a checkout can read the backlog with no install, no DB, no admin
+   token and no network.
+2. The Lucille backend imports the same module, so a status derived by the API
+   and a status rendered into the committed markdown cannot disagree — one
+   implementation, two callers. That divergence is a failure this repo has been
+   bitten by before.
+3. It is the extraction seam. The roadmap is being prepared to run as its own
+   product whose default store is a single SQLite file with nothing to
+   provision; a package that pulled in a web framework or an ORM could not be
+   adopted by another repo without adopting Lucille with it.
+
+## Storage
+
+`store.py` is the schema — one SQLite file, `CREATE TABLE IF NOT EXISTS` on first
+open, no migration step. `stores.py` is what you talk to:
+
+| | `LocalStore` | `ApiStore` |
+|---|---|---|
+| needs | a writable path | a `call(method, path, payload)` |
+| provisioning | none | a running host |
+| `claim`/`release` | one `BEGIN IMMEDIATE` transaction | one HTTP request |
+| `impact` | raises `Unsupported` | the host's tickets |
+
+Both satisfy the same `Store` protocol, so a caller never branches on which it
+holds. `ApiStore` is constructed with the host's own caller and holds no token,
+no URL and no `urllib` import — auth stays entirely a host concern, and
+`test_stores.py` asserts that rather than trusting it.
+
+```python
+from roadmap_core.stores import LocalStore
+
+with LocalStore("roadmap/roadmap.db") as store:   # created if absent
+    store.upsert_item({"key": "a-thing", "title": "A thing"})
+    store.claim("a-thing", by="claude/some-branch")
+```
+
+From the CLI, `--source local` on `push`, `claim`, `release` and `status`, or
+`ROADMAP_SOURCE=local` once. `ROADMAP_STORE` sets the path.
+
+## Adopting it in another project
+
+Measured end to end by `tests/test_adoption.py`, which runs the CLI as a
+subprocess against a scratch project with nothing on the path but this package
+— no backend, no FastAPI, no SQLAlchemy, no Postgres, no server, no token.
+
+```bash
+pip install "roadmap-core[files]"   # [files] adds PyYAML, which authoring needs
+mkdir -p roadmap/items
+export ROADMAP_SOURCE=local
+```
+
+That is the whole install. `roadmap` is a console script that comes with the
+package — there is nothing to copy. (It used to say `curl -o scripts/roadmap.py
+<this repo>/scripts/roadmap.py`, and this repo is private, so the package was
+installable, importable and useless to anyone outside it.)
+
+Then the ordinary loop, which needs nothing else:
+
+```bash
+cat > roadmap/items/first-thing.yaml <<'YAML'
+id: first-thing
+title: The first thing to do
+status: ready
+evidence: |
+  Why this is worth doing, and how you will know it worked.
+YAML
+
+roadmap push            # files -> store
+roadmap ready           # what is startable
+roadmap claim first-thing
+roadmap release first-thing
+```
+
+The store is one SQLite file at `roadmap/roadmap.db`. There is nothing to
+provision and no migration to run: it is created on first open.
+
+**Two things that are conventions rather than choices**, both found by doing
+this rather than by reading the code:
+
+- **Your project root is the nearest ancestor holding `roadmap/items` or
+  `.git`**, so the commands work from anywhere inside it. Set
+  `ROADMAP_REPO_ROOT` to pin it. Deliberately not bare `roadmap/`: that is a
+  directory the tool *creates*, so keying on it let one command run in the
+  wrong place mint the marker that made that place look like a project
+  forever after.
+- **Authoring is writing a YAML file**, not calling an API. `push` is what
+  moves it into the store; there is no `roadmap new`. That is deliberate:
+  filing an item belongs in a diff somebody reviews.
+
+`ROADMAP_SOURCE=local` selects the SQLite store. Without it the CLI expects the
+API store, which is how Lucille runs it — see `roadmap_core.stores`.
+
+### CI
+
+Copy `templates/roadmap.yml` to `.github/workflows/roadmap.yml`. That is the
+whole CI story for the floor:
+
+```
+push      # files -> store, rebuilt fresh each run
+validate  # schema, dangling dependencies, cycles
+sync --check   # is the committed ROADMAP.md still what the graph renders?
+```
+
+No schedule, no credentials, no bot identity, no commit back to the default
+branch, no self-hosted runner. `tests/test_adoption.py` reads the commands out
+of that file and runs them, so a template that has drifted from the CLI fails
+rather than reading as tested.
+
+The third line is the one that earns the workflow. `ROADMAP.md` is generated but
+committed — that is what lets an agent read the backlog with no install and no
+network — and a generated file nobody regenerates is a file that lies.
+
+**Do not commit `roadmap/roadmap.db`.** It is derived: `push` rebuilds it from
+the YAML on first open, and a binary file in git conflicts on every claim. The
+files are the record; the store is the transaction that decides who gets one.
+
+### Upgrading to a served store
+
+The floor's simplicity comes from one property: the store is inside the
+checkout, so there is no second copy to drift from. Move the store to a server —
+so that claims are visible across machines the moment they are taken, rather
+than when a branch merges — and four things come back, none of which the
+template can supply for you:
+
+| What returns | Why |
+|---|---|
+| A **credential** step | the store is now behind auth, and the CLI needs a token per run |
+| A **wait-for-reachable** step | a concurrent deploy can hold the store down, and being early is not being wrong |
+| `pull` and a **bot commit** | the store now knows things no checkout does, and they have to land in the files an agent reads |
+| A **schedule** | finishing an item is usually a code change somewhere else entirely, so no path filter can catch it — only re-asking on a clock can |
+
+`ApiStore` is constructed with your own caller, so the auth stays yours (see the
+table under [Storage](#storage)). Lucille's `.github/workflows/roadmap-sync.yml`
+is the worked example of all four, and the reason it is not shipped as a
+template: almost every line of it is a consequence of Lucille's own deployment,
+and handing an adopter that machinery for a problem they do not have reads as
+required rather than as one option.
+
+## What is NOT here
+
+HTTP, auth, and the CLI. The graph is pure functions over plain dicts keyed by
+`key`, so the same code serves DB rows, API payloads and parsed YAML with no
+adapter. Lucille's own persistence stays in `backend/app/crud/roadmap.py` over
+SQLAlchemy; the two definitions of the same three tables are held together by
+`backend/tests/test_roadmap_store_parity.py`, which asserts both the columns and
+the row dicts the two readers produce.
+
+The package's tests live in `tests/` here and import nothing outside the stdlib.
+`.github/workflows/roadmap-core-tests.yml` runs them in a job that fails if
+`app`, `fastapi`, `sqlalchemy` or `yaml` can be imported at all — the isolation
+is asserted, not assumed.

roadmap_core-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "roadmap-core"
+version = "0.1.0"
+description = "The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend."
+requires-python = ">=3.11"
+readme = "README.md"
+license = { text = "MIT" }
+keywords = ["roadmap", "backlog", "dependency-graph", "agents", "planning"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Build Tools",
+]
+# Intentionally dependency-free, and this is load-bearing rather than tidy.
+#
+# Two callers need this logic and neither may drag the other in: the Lucille
+# backend (which has a DB) and `scripts/roadmap.py` (which runs in any checkout
+# with no app dependencies, no DB and no network — that is what lets an agent
+# read the backlog offline). The script loads `roadmap_core/graph.py` BY PATH for
+# exactly that reason, which only keeps working while this stays importable with
+# nothing installed.
+#
+# It is also the extraction seam. The roadmap is being prepared to run as its own
+# product whose default store is a single SQLite file; a package that pulls in a
+# web framework or an ORM could not be adopted by another repo without adopting
+# Lucille with it.
+dependencies = []
+
+# pytest only, and nothing else. The tests here are synthetic by rule — no DB, no
+# app, no committed roadmap/items/ — so a repo adopting this package can run its
+# proof of correctness without adopting anything from Lucille. That is checked in
+# CI by installing ONLY this package and running them.
+[project.optional-dependencies]
+# Authoring an item IS writing `roadmap/items/<key>.yaml` — there is no
+# `roadmap.py new`, deliberately, because filing work belongs in a diff
+# somebody reviews. So the file paths need a YAML parser, and an adopter who
+# installs the bare package finds that out from `push` rather than from here:
+#
+#     PyYAML required for --source files (pip install pyyaml)
+#
+# Measured on 2026-08-18 by `tests/test_adoption.py` running in the isolation
+# job, after the same test passed locally on a machine that happened to have
+# PyYAML installed. An extra rather than a hard dependency because the top of
+# this file means what it says: the store, the graph and the impact rule stay
+# importable with nothing installed, which is what lets the backend and a bare
+# checkout both use them. `[files]` is what the CLI needs, not what the library
+# needs.
+#
+# Deliberately NOT in `dev`. `roadmap-core-tests.yml` asserts that `yaml` is
+# not importable in that job — the guard that keeps "this package stands alone"
+# from quietly becoming false. Putting PyYAML in `dev` to make one test pass
+# would have disabled that guard to do it, which is the trade it exists to
+# refuse. The adoption test runs in its own job with `[files]` installed.
+files = ["pyyaml>=6"]
+dev = ["pytest>=8"]
+
+# The CLI ships WITH the package, and this line is the reason adopting it works
+# at all. `README.md` used to say `curl -o scripts/roadmap.py <this repo>/...`,
+# and this repo is private — so the package was installable, importable, and
+# useless, because the 2000-line program that drives it could not be obtained.
+# A dependency-free library whose tool you cannot get is not an adoptable tool.
+[project.scripts]
+roadmap = "roadmap_core.cli:main"
+
+[project.urls]
+Source = "https://github.com/gald33/lucille/tree/main/roadmap-core"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["roadmap_core*"]
+
+# The CI template an adopter copies. Shipped in the sdist rather than left in
+# the repo, because the README tells them to copy it and a pip install is all
+# some adopters will ever have of this project.
+[tool.setuptools.data-files]
+"share/roadmap-core/templates" = ["templates/roadmap.yml"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]

roadmap_core-0.1.0/roadmap_core/__init__.py

@@ -0,0 +1,21 @@
+"""The roadmap graph, store and CLI, as a standalone package.
+
+Import the graph explicitly rather than re-exporting it here::
+
+    from roadmap_core import graph
+    from roadmap_core.graph import derive_status, validate_graph
+
+Kept bare on purpose, for a reason that outlived the one it was written for.
+It used to be that ``scripts/roadmap.py`` loaded ``graph.py`` *by path* with
+nothing installed, and a package ``__init__`` importing submodules would have
+broken that. The CLI lives in here now (``roadmap_core.cli``) and imports its
+siblings normally, so that particular hazard is gone.
+
+What remains is better: ``graph``, ``store`` and ``stores`` are importable with
+no third-party package present at all, and ``cli`` is importable without
+PyYAML — it imports it inside the two functions that parse item files. A
+``__init__`` that reached for ``cli`` would drag that requirement onto every
+caller of the graph, including the Lucille backend, which needs none of it.
+``roadmap-core-tests.yml`` asserts exactly this by running the suite in an
+environment where ``yaml`` cannot be imported at all.
+"""