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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roadmap-core
-Version: 0.2.2
+Version: 0.2.3
 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:
 

{roadmap_core-0.2.2 → roadmap_core-0.2.3}/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:
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "roadmap-core"
-version = "0.2.2"
+version = "0.2.3"
 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"

{roadmap_core-0.2.2 → roadmap_core-0.2.3}/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:

{roadmap_core-0.2.2 → roadmap_core-0.2.3}/roadmap_core/stores.py

@@ -172,6 +172,20 @@ def _row_to_arc(row: sqlite3.Row) -> dict[str, Any]:
 class LocalStore:
     """The roadmap in one SQLite file, with no server anywhere.
 
+    **Claim on the floor.** This store takes a file's `claimed_by`/`claimed_at`
+    when it CREATES an item, and ignores them on update. `ApiStore` never does.
+    That asymmetry is deliberate and is the ruling recorded in
+    `a-claim-cannot-survive-the-floors-ci`: here the store is EPHEMERAL — CI
+    deletes it and rebuilds it from `roadmap/items/*.yaml` every run — so the
+    file is the only durable record a claim has, and dropping it made a held item
+    render as `ready` and `sync --check` fail for as long as anybody was working.
+    Against a SERVED store the file is a projection of a store that outlives it,
+    and honouring a claim from a stale checkout would recreate one the store had
+    already released — the resurrection class `roadmap_prunes` exists to prevent.
+
+    One field, two meanings, decided by which store you are holding. Stated here
+    because it is not guessable from the field's name.
+
     Owns its connection and closes it, so a caller can use it as a context
     manager and a test does not leak file handles into the next test.
     """
@@ -260,6 +274,10 @@ class LocalStore:
             payload["id"] = store.new_id()
             payload["status"] = item.get("status") or "ready"
             payload["created_at"] = now
+            # The claim, on CREATE only, for the same reason as `status` and with
+            # the same asymmetry — see the class docstring's "claim on the floor".
+            payload["claimed_by"] = item.get("claimed_by")
+            payload["claimed_at"] = item.get("claimed_at")
             names = ", ".join(payload)
             marks = ", ".join("?" for _ in payload)
             self._conn.execute(
@@ -326,11 +344,23 @@ class LocalStore:
             raise StoreError(f"no such item: {key}")
         now = _utcnow_iso()
         done_at = row["done_at"] or (now if status == "done" else None)
-        self._conn.execute(
-            "UPDATE roadmap_items SET status = ?, done_at = ?, updated_at = ?"
-            " WHERE key = ?",
-            (status, done_at, now, key),
-        )
+        if status == "done":
+            # Finishing drops the hold, matching the served path — and matching
+            # what the CLI already prints ("done also drops the claim"), which it
+            # printed here while nothing happened. Finishing is the one moment a
+            # hold is definitely over, and releasing separately is the step that
+            # never happens because nothing prompts it.
+            self._conn.execute(
+                "UPDATE roadmap_items SET status = ?, done_at = ?, updated_at = ?,"
+                " claimed_by = NULL, claimed_at = NULL WHERE key = ?",
+                (status, done_at, now, key),
+            )
+        else:
+            self._conn.execute(
+                "UPDATE roadmap_items SET status = ?, done_at = ?, updated_at = ?"
+                " WHERE key = ?",
+                (status, done_at, now, key),
+            )
         return self.get_item(key) or {}
 
     def delete_item(self, key: str) -> bool:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roadmap-core
-Version: 0.2.2
+Version: 0.2.3
 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:
 

{roadmap_core-0.2.2 → roadmap_core-0.2.3}/tests/test_adoption.py

@@ -29,7 +29,9 @@ empty backlog for an afternoon.
 
 from __future__ import annotations
 
+import argparse
 import os
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -373,3 +375,122 @@ def test_the_version_is_answerable_without_a_subcommand(project):
 
     assert result.returncode == 0
     assert "roadmap-core" in result.stdout
+
+
+def test_the_version_names_the_code_that_is_running_not_the_one_installed(
+    project, tmp_path
+):
+    """A shadowed install must not be reported as the running one.
+
+    `metadata.version()` reads the INSTALLED distribution whether or not that is
+    what got imported, and the two diverge on `PYTHONPATH=.` in a checkout, an
+    editable install pointing at a moved directory, or any wrapper that prepends
+    to `sys.path`. Measured in this repository on 2026-08-22: `doctor` printed
+    `0.2.1` while running 0.2.2 from a checkout.
+
+    This is the one command where that is disqualifying rather than untidy — it
+    exists BECAUSE two installs at different versions could not be told apart, so
+    a version string able to name the wrong one reintroduces its own subject.
+
+    Done by really shadowing the package rather than by patching `metadata`: a
+    copy at a path nobody would mistake for the install, imported by putting it
+    first on `PYTHONPATH`.
+    """
+    shadow = tmp_path / "shadow"
+    shutil.copytree(PACKAGE_ROOT / "roadmap_core", shadow / "roadmap_core")
+
+    env = dict(os.environ)
+    env["PYTHONPATH"] = str(shadow)
+    env["ROADMAP_SOURCE"] = "local"
+    result = subprocess.run(
+        [sys.executable, "-m", "roadmap_core.cli", "--version"],
+        cwd=project, env=env, capture_output=True, text=True, timeout=60,
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert str(shadow / "roadmap_core") in result.stdout, (
+        "the version must name where the running code came from when that is not "
+        f"the installed distribution — got: {result.stdout!r}"
+    )
+
+
+# --- claiming, on the floor, end to end ---------------------------------------
+
+
+def test_a_floor_project_can_claim_and_still_pass_its_own_ci(project):
+    """The failure `a-claim-cannot-survive-the-floors-ci` describes, run whole.
+
+    Claim an item, commit what the CLI tells you to commit, then let CI rebuild
+    the store from the files — which is what `.github/workflows/roadmap.yml`
+    does on every run, because on the floor the store is a SQLite file that does
+    not exist until `push` creates it.
+
+    Before the fix this ended in `ARCS.md is stale — run 'roadmap sync'`, and
+    `sync` did not fix it: the file said `claimed`, a fresh push rendered
+    `ready`, and the two could not agree while anybody held anything. The floor's
+    CI was red for exactly as long as its coordination feature was in use.
+
+    The store is deleted between the two halves ON PURPOSE. Checking against the
+    warm store the claim was made in is what hid this — it agrees with itself.
+    """
+    assert run(project, "push").returncode == 0
+    # `--by` explicitly: the scratch project is not a git repository, so
+    # `current_branch()` has nothing to read and the holder would be the literal
+    # string "unknown" — which would still pass a test that only checked the
+    # claim survived, while proving nothing about the name travelling with it.
+    assert run(project, "claim", "first-thing", "--by", "claude/holder").returncode == 0
+    assert run(project, "sync").returncode == 0
+
+    (project / "roadmap" / "roadmap.db").unlink()          # as CI starts
+    assert run(project, "push").returncode == 0
+    assert run(project, "validate").returncode == 0
+
+    checked = run(project, "sync", "--check")
+    assert checked.returncode == 0, (
+        "a claimed item makes the committed markdown unreproducible:\n"
+        f"{checked.stdout}\n{checked.stderr}"
+    )
+    # And the holder survived, not merely the status: a rebuild that kept
+    # `claimed` while losing WHO holds it would still leave the next session
+    # unable to tell whether the item is theirs.
+    assert "CLAIMED" in run(project, "list").stdout
+    assert "claude/holder" in run(project, "show", "first-thing").stdout
+
+
+def test_the_served_path_still_refuses_to_carry_a_claim(project, monkeypatch):
+    """Acceptance 2, asserted rather than assumed.
+
+    The same move against a SERVED store is the resurrection class: its store
+    outlives the checkout, so a push from a stale clone would recreate a claim
+    that store had already released. The fix must be visible on the floor and
+    absent over the API, and the only way to know is to look at what `push`
+    actually sends.
+    """
+    import importlib.util
+
+    spec = importlib.util.spec_from_file_location(
+        "roadmap_core.cli", PACKAGE_ROOT / "roadmap_core" / "cli.py"
+    )
+    cli = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(cli)
+
+    monkeypatch.setattr(cli, "REPO_ROOT", project)
+    monkeypatch.setattr(cli, "ITEMS_DIR", project / "roadmap" / "items")
+    monkeypatch.setattr(cli, "ARCS_DIR", project / "roadmap" / "arcs")
+    (project / "roadmap" / "items" / "first-thing.yaml").write_text(
+        ITEM + "claim:\n  by: claude/stale-checkout\n  at: '2026-01-01T00:00:00Z'\n"
+    )
+
+    sent: list[dict] = []
+    monkeypatch.setattr(cli, "_api", lambda m, p, payload=None: sent.append(payload or {}))
+    monkeypatch.setattr(cli, "load_from_db", dict)
+
+    cli.cmd_push(argparse.Namespace(source="db"))
+
+    item_payloads = [p for p in sent if "evidence" in p]
+    assert item_payloads, "push sent no item at all"
+    for payload in item_payloads:
+        assert "claimed_by" not in payload, (
+            "the served store must not be handed a claim from a file — a stale "
+            f"checkout would resurrect a released one: {payload}"
+        )

{roadmap_core-0.2.2 → roadmap_core-0.2.3}/tests/test_stores.py

@@ -452,3 +452,85 @@ def test_json_columns_named_by_the_schema_are_the_ones_decoded(db):
     item = db.items()["alpha"]
     for column in store.JSON_COLUMNS["roadmap_items"]:
         assert not isinstance(item[column], str), f"{column} came back as raw JSON text"
+
+
+# --- claim on the floor -------------------------------------------------------
+#
+# The store here is EPHEMERAL: CI deletes it and rebuilds it from the committed
+# YAML every run. So a claim that a file records has to survive being pushed, or
+# a held item renders as `ready` and the committed markdown can never match what
+# CI generates. That is `a-claim-cannot-survive-the-floors-ci`, and these pin the
+# ruling: authoritative on the floor, CREATE only, exactly like `status`.
+
+
+def test_a_claim_in_the_file_survives_a_rebuild_of_the_store(db):
+    db.upsert_item({
+        "key": "alpha",
+        "title": "Alpha",
+        "status": "claimed",
+        "claimed_by": "claude/some-branch",
+        "claimed_at": "2026-08-22T10:00:00+00:00",
+    })
+    item = db.items()["alpha"]
+    assert item["claimed_by"] == "claude/some-branch"
+    assert item["claimed_at"] == "2026-08-22T10:00:00+00:00"
+    assert item["status"] == "claimed"
+
+
+def test_an_update_cannot_move_a_claim(db):
+    """CREATE only, for the same reason `status` is.
+
+    On update the store is the live record of who holds what — a push from a
+    checkout that predates a release would otherwise hand the item back to a
+    session that has already let go.
+    """
+    db.upsert_item({"key": "alpha", "title": "Alpha"})
+    db.claim("alpha", by="claude/live")
+
+    db.upsert_item({
+        "key": "alpha",
+        "title": "Alpha",
+        "claimed_by": "claude/stale-checkout",
+        "claimed_at": "2026-01-01T00:00:00+00:00",
+    })
+
+    assert db.items()["alpha"]["claimed_by"] == "claude/live"
+
+
+def test_an_unclaimed_file_creates_an_unclaimed_item(db):
+    """The ordinary case: no claim block, no claim. Asserted because the create
+    path now writes those columns explicitly rather than leaving them to the
+    schema default, and `None` is the value that has to arrive."""
+    db.upsert_item({"key": "alpha", "title": "Alpha"})
+    item = db.items()["alpha"]
+    assert item["claimed_by"] is None
+    assert item["claimed_at"] is None
+
+
+def test_done_drops_the_claim(db):
+    """The CLI has always printed "done also drops the claim". On the floor it
+    did not — the served path clears the hold and this one did not, and nobody
+    could see the difference because a claim never survived a rebuild anyway.
+
+    Fixing claims-survive-a-rebuild is what made this visible: the notice about
+    an unreleased hold started firing on an item that had just been finished.
+    """
+    db.upsert_item({"key": "alpha", "title": "Alpha"})
+    db.claim("alpha", by="claude/holder")
+
+    row = db.set_status("alpha", "done")
+
+    assert row["status"] == "done"
+    assert row["claimed_by"] is None
+    assert row["claimed_at"] is None
+
+
+def test_a_status_that_is_not_done_leaves_the_claim_alone(db):
+    """`verifying` explicitly does NOT drop it: the branch that shipped the work
+    still owns confirming it landed."""
+    db.upsert_item({"key": "alpha", "title": "Alpha"})
+    db.claim("alpha", by="claude/holder")
+
+    row = db.set_status("alpha", "verifying")
+
+    assert row["claimed_by"] == "claude/holder"