roadmap-core 0.2.2__tar.gz → 0.3.0__tar.gz

{roadmap_core-0.2.2/roadmap_core.egg-info → roadmap_core-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roadmap-core
-Version: 0.2.2
+Version: 0.3.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/roadmap-core
@@ -129,6 +129,17 @@ FAIL  store       roadmap/roadmap.db holds 0 items while roadmap/items/ holds 7.
                   Seed it: `roadmap push`
 ```
 
+**Who owns a claim depends on which store you have.** On the SQLite floor the
+file is authoritative: CI rebuilds the store from `roadmap/items/*.yaml` every
+run, so `push` takes a file's `claim` when it CREATES the item — otherwise a
+held item renders as `ready` and `sync --check` fails for as long as anybody is
+working. Against a served store the file is a *projection* of a store that
+outlives the checkout, so a claim in a file is never pushed: a stale clone would
+recreate one the store had already released. Either way `push` ignores it on
+UPDATE, because the store is the live record of who holds what.
+
+Not guessable from the field's name, which is why it is written down here.
+
 **Two things that are conventions rather than choices**, both found by doing
 this rather than by reading the code:
 
@@ -145,6 +156,41 @@ this rather than by reading the code:
 `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`.
 
+### Agents (MCP)
+
+`roadmap-mcp` serves the same graph to a coding agent as MCP tools over stdio —
+`ready`, `list`, `show`, `validate`, `claim`, `release`, `set_status`. Point a
+client at it:
+
+```json
+{
+  "mcpServers": {
+    "roadmap": {
+      "command": "roadmap-mcp",
+      "env": { "ROADMAP_SOURCE": "local" }
+    }
+  }
+}
+```
+
+**There is no extra to install and no SDK underneath.** `mcp_server.py` speaks
+the JSON-RPC protocol in stdlib, so it is present wherever the package is —
+which is the same reason the rest of this package is dependency-free, applied to
+one more caller. An extra would be one an adopter can forget, for a server that
+needs nothing.
+
+**Reads default to the files**, so an agent in a fresh clone can ask what to
+work on with no store, no server and no token. Writes need a store to arbitrate
+them: set `ROADMAP_SOURCE=local` as above, or the write tools expect the API
+store. There is deliberately no `files` write target — a claim nothing
+adjudicated is not a claim, and two agents could each hold the same item.
+
+**A write tells the agent to commit something, and it means it.** `claim`,
+`release` and `set_status` project into `roadmap/items/<key>.yaml`, and on the
+floor that projection *is* the durable record — an unmerged one is a claim no
+other checkout can see. The tool result carries the CLI's own words for this
+under `notes`.
+
 ### CI
 
 Copy `templates/roadmap.yml` to `.github/workflows/roadmap.yml`. That is the

{roadmap_core-0.2.2 → roadmap_core-0.3.0}/README.md

@@ -108,6 +108,17 @@ FAIL  store       roadmap/roadmap.db holds 0 items while roadmap/items/ holds 7.
                   Seed it: `roadmap push`
 ```
 
+**Who owns a claim depends on which store you have.** On the SQLite floor the
+file is authoritative: CI rebuilds the store from `roadmap/items/*.yaml` every
+run, so `push` takes a file's `claim` when it CREATES the item — otherwise a
+held item renders as `ready` and `sync --check` fails for as long as anybody is
+working. Against a served store the file is a *projection* of a store that
+outlives the checkout, so a claim in a file is never pushed: a stale clone would
+recreate one the store had already released. Either way `push` ignores it on
+UPDATE, because the store is the live record of who holds what.
+
+Not guessable from the field's name, which is why it is written down here.
+
 **Two things that are conventions rather than choices**, both found by doing
 this rather than by reading the code:
 
@@ -124,6 +135,41 @@ this rather than by reading the code:
 `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`.
 
+### Agents (MCP)
+
+`roadmap-mcp` serves the same graph to a coding agent as MCP tools over stdio —
+`ready`, `list`, `show`, `validate`, `claim`, `release`, `set_status`. Point a
+client at it:
+
+```json
+{
+  "mcpServers": {
+    "roadmap": {
+      "command": "roadmap-mcp",
+      "env": { "ROADMAP_SOURCE": "local" }
+    }
+  }
+}
+```
+
+**There is no extra to install and no SDK underneath.** `mcp_server.py` speaks
+the JSON-RPC protocol in stdlib, so it is present wherever the package is —
+which is the same reason the rest of this package is dependency-free, applied to
+one more caller. An extra would be one an adopter can forget, for a server that
+needs nothing.
+
+**Reads default to the files**, so an agent in a fresh clone can ask what to
+work on with no store, no server and no token. Writes need a store to arbitrate
+them: set `ROADMAP_SOURCE=local` as above, or the write tools expect the API
+store. There is deliberately no `files` write target — a claim nothing
+adjudicated is not a claim, and two agents could each hold the same item.
+
+**A write tells the agent to commit something, and it means it.** `claim`,
+`release` and `set_status` project into `roadmap/items/<key>.yaml`, and on the
+floor that projection *is* the durable record — an unmerged one is a claim no
+other checkout can see. The tool result carries the CLI's own words for this
+under `notes`.
+
 ### CI
 
 Copy `templates/roadmap.yml` to `.github/workflows/roadmap.yml`. That is the

{roadmap_core-0.2.2 → roadmap_core-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roadmap-core"
-version = "0.2.2"
+version = "0.3.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"
@@ -63,6 +63,11 @@ dev = ["pytest>=8"]
 # A dependency-free library whose tool you cannot get is not an adoptable tool.
 [project.scripts]
 roadmap = "roadmap_core.cli:main"
+# The MCP bridge, and no extra to install it: `mcp_server.py` speaks the stdio
+# protocol in stdlib rather than taking the SDK, so it is already installed
+# wherever the package is. An extra here would be an extra that is always
+# empty — and one an adopter could forget, for a server that needs nothing.
+roadmap-mcp = "roadmap_core.mcp_server:main"
 
 [project.urls]
 Source = "https://github.com/gald33/roadmap-core"

{roadmap_core-0.2.2 → roadmap_core-0.3.0}/roadmap_core/cli.py

@@ -899,7 +899,16 @@ def cmd_push(args: argparse.Namespace) -> int:
         }
         try:
             if local is not None:
-                local.upsert_item(payload)
+                # The claim goes to the LOCAL store only. Its store is ephemeral
+                # — CI rebuilds it from these files every run — so the file is
+                # the only durable record a claim has. The served store outlives
+                # the checkout, where the same move would recreate a claim it had
+                # already released. See `LocalStore`'s "claim on the floor".
+                local.upsert_item(dict(
+                    payload,
+                    claimed_by=item.get("claimed_by"),
+                    claimed_at=item.get("claimed_at"),
+                ))
             else:
                 _api("PUT", f"/admin/roadmap/{key}", payload)
         except stores.Pruned:
@@ -1000,7 +1009,15 @@ def cmd_status(args: argparse.Namespace) -> int:
             file=sys.stderr,
         )
     if args.status == "done":
-        print("done also drops the claim — `roadmap.py prune` when you are ready to clear it")
+        # The store drops the hold; the FILE has to lose it too, or the next
+        # push puts it straight back. On the floor that is not a cosmetic lag —
+        # the file is where a claim durably lives there, so a stale block in it
+        # is the claim, and `sync --check` goes red on an item nobody holds.
+        # Projected here rather than left to `pull`, which is a served-store
+        # command a floor project never runs.
+        with switchboard_write_lock(args.key):
+            _claim_projected(args.key, None)
+        print("done also drops the claim — `roadmap prune` when you are ready to clear it")
         # No lease to drop here any more. This used to release the long-lived
         # mirror, which the store's `done` side effect would otherwise leave
         # reading as "claimed and alive" for up to four hours after the roadmap
@@ -1915,22 +1932,46 @@ def cmd_validate(args: argparse.Namespace) -> int:
 
 
 def installed_version() -> str:
-    """The version of the distribution this module was imported from.
-
-    A source checkout that was never installed has no distribution metadata,
-    which is a legitimate way to run the CLI and must not raise. It is still
-    worth distinguishing in the output: "which version is this" and "there is no
-    package here, you are running a directory" are different answers to the same
-    question, and only one of them can be compared against a pin.
+    """The version of the code that is actually running.
+
+    Not simply `metadata.version("roadmap-core")`, which reports the version of
+    the INSTALLED DISTRIBUTION whether or not that is what got imported. Those
+    diverge whenever a source tree shadows the install — `PYTHONPATH=.` in a
+    checkout, an editable install left pointing at a directory that moved, a
+    `sys.path` entry a wrapper script prepended. In every one of those the
+    distribution's metadata is still perfectly readable and describes a copy of
+    the code nobody is executing.
+
+    That is a small inaccuracy in most commands and a disqualifying one here.
+    This function exists because two installs at different versions could not be
+    told apart; a version string that can name the wrong one reintroduces the
+    problem it was added to solve. Measured 2026-08-22 in this repository:
+    `doctor` reported `0.2.1` while running 0.2.2 from a checkout.
+
+    So the location is compared, and a mismatch is stated rather than resolved —
+    which one is "right" depends on what the caller meant, and printing both is
+    the only answer that cannot be wrong.
     """
     try:
-        from importlib.metadata import PackageNotFoundError, version
+        from importlib.metadata import PackageNotFoundError, distribution
     except ImportError:  # pragma: no cover - stdlib since 3.8
         return "unknown"
+
+    running_from = Path(__file__).resolve().parent
     try:
-        return version("roadmap-core")
+        dist = distribution("roadmap-core")
     except PackageNotFoundError:
-        return "not installed (running from a source tree)"
+        return f"not installed (running from {running_from})"
+
+    declared = dist.version
+    try:
+        installed_at = Path(str(dist.locate_file("roadmap_core"))).resolve()
+    except Exception:  # noqa: BLE001 - a path we cannot resolve is a mismatch we cannot rule out
+        return declared
+
+    if installed_at == running_from:
+        return declared
+    return f"{declared} installed, but running from {running_from}"
 
 
 class _Check: