lemming-cli 0.6.1__tar.gz → 0.7.0__tar.gz

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lemming-cli
-Version: 0.6.1
+Version: 0.7.0
 Summary: An autonomous, iterative task runner for AI coding agents.
 Project-URL: Homepage, https://github.com/owahltinez/lemming
 Project-URL: Repository, https://github.com/owahltinez/lemming
@@ -445,6 +445,14 @@ These come before the subcommand and apply to all of them.
   - `--yolo`: Run the runner in auto-approve mode (default: True).
   - `--env`: Set environment variables for the runner (e.g., `--env KEY=VALUE`).
   - `--no-defaults`: Skip default flag injection for known runners.
+  - `--until <task-id>`: Stop between tasks once that task has completed or
+    failed, printing `Reached milestone <id>; M pending.` so a supervising
+    agent can review before queueing the next milestone. Tasks inserted ahead
+    of it still run; if the roadmap hook supersedes it, the run continues until
+    every replacement has settled. Deleting it stops the run with exit 1.
+  - `--max-tasks N`: Stop between tasks once `N` have completed or failed,
+    printing `Stopped after N tasks; M pending.` Attempts that leave a task
+    pending do not count. Combine with `--until` as a budget cap.
   - `--`: Use `--` to pass any flag directly to the underlying runner. A
     per-task `--runner`/`--model` overrides anything passed here.
 - **`exec [<description>]`**: Run one task, or one set of reviews, outside any

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/README.md

@@ -425,6 +425,14 @@ These come before the subcommand and apply to all of them.
   - `--yolo`: Run the runner in auto-approve mode (default: True).
   - `--env`: Set environment variables for the runner (e.g., `--env KEY=VALUE`).
   - `--no-defaults`: Skip default flag injection for known runners.
+  - `--until <task-id>`: Stop between tasks once that task has completed or
+    failed, printing `Reached milestone <id>; M pending.` so a supervising
+    agent can review before queueing the next milestone. Tasks inserted ahead
+    of it still run; if the roadmap hook supersedes it, the run continues until
+    every replacement has settled. Deleting it stops the run with exit 1.
+  - `--max-tasks N`: Stop between tasks once `N` have completed or failed,
+    printing `Stopped after N tasks; M pending.` Attempts that leave a task
+    pending do not count. Combine with `--until` as a budget cap.
   - `--`: Use `--` to pass any flag directly to the underlying runner. A
     per-task `--runner`/`--model` overrides anything passed here.
 - **`exec [<description>]`**: Run one task, or one set of reviews, outside any

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/SKILL.md

@@ -153,33 +153,85 @@ recorded progress, so the project survives context limits.
 lemming goal "Add offline support with a service worker and a sync queue"
 lemming add "Register the service worker and cache the app shell"
 lemming add "Queue writes in IndexedDB while offline"
+lemming add "Bump the service worker cache version" --oneshot
 lemming run                                  # runs until the queue drains
+lemming run --until <task-id>                # or stops once that task settles
 ```
 
 The loop shares one workspace across all its tasks, so isolate the **whole run**
 — one branch or worktree created before `lemming run`, driven with
 `lemming -C <worktree> run` — never one per task.
 
-Check on it, and read what an agent actually did:
+**Mark mechanical tasks `--oneshot`.** After every other task, review hooks run
+and a roadmap hook may revise the queue; each hook is a full agent run, so a
+typo fix, rename, version bump, or cleanup without `--oneshot` takes several
+times longer than the work itself. Reserve hooked tasks for changes in
+behavior. `lemming hooks list` shows the hooks; `lemming hooks disable <name>`
+turns one off for the project.
+
+### Supervise in milestones
+
+Never run the whole roadmap and poll it from one context. Every `status` call
+lands in your context window, and the run outlives it. Split the queue into
+milestones instead:
+
+1. Queue the whole roadmap, pick the task that ends the first milestone, and
+   run `lemming run --until <task-id>`. It blocks, runs anything the roadmap
+   hook inserts ahead of that task, follows the task through any split, and
+   exits printing `Reached milestone <id>; M pending.` or
+   `All tasks completed!`. A non-zero exit means a task failed, the queue is
+   blocked, or the milestone task was deleted; `lemming status --brief` shows
+   which. Add `--max-tasks N` as a budget cap when a runaway roadmap hook
+   would be expensive.
+2. Between milestones, judge direction: `lemming status --brief`, then
+   `lemming status <id>` for the tasks that matter. Re-plan with `add`, `edit`,
+   `supersede`, or `delete`, then run the next milestone.
+3. Delegate each milestone to a subagent when one exists, so the polling and
+   the log reading stay out of your context. The subagent reports back in the
+   fixed shape below, nothing more.
+
+This is how a stronger model directs cheaper ones: `lemming config set runner`
+and `config set model` pick the worker; the supervising agent only reads
+status between milestones and decides what happens next.
+
+Checking on a running milestone is fine when a task might be stuck, but poll
+sparingly and read the smallest thing that answers the question:
 
 ```sh
-lemming status              # queue, attempts, and recorded progress
-lemming status <id>         # one task in detail, including its runner command
-lemming logs                # the active task's log, or logs <id> for one task
+lemming status --brief      # one row per task, no descriptions
+lemming status <id>         # Run Time against the time limit, progress entries
+lemming logs <id> | tail -n 30   # never the whole log
 ```
 
-Adjust it while it runs — new tasks are picked up automatically:
+A task is stuck when its run time approaches the limit with no new progress
+entries and the log tail shows the same step repeating. Otherwise leave it.
+
+Adjust the queue while it runs — new tasks are picked up automatically:
 
 ```sh
 lemming add "Add a retry backoff to the sync queue" --index 0  # jump the queue
 lemming stop --after-current-task                             # drain, then stop
 ```
 
-After each task, review hooks run automatically and a roadmap hook may revise
-the queue. `lemming hooks list` shows them; `lemming hooks disable <name>` turns
-one off for the project. Queue a mechanical task — a typo fix, a version bump, a
-rename — with `lemming add "..." --oneshot` to skip those hooks when it
-completes.
+### Report tersely
+
+Your own words fill context faster than any tool. Whether reporting to a user or
+to a parent agent:
+
+- Report one milestone in this shape and no other: outcome (`done`, `failed`,
+  `blocked`), task IDs that settled, files changed, one line of guidance for the
+  next milestone. Skip anything that can be re-read from `lemming status`.
+- Never paste `status`, `logs`, test output, or diffs into a message or a
+  progress entry; name the task ID or file and let the reader fetch it.
+- Progress entries are one line each. Evidence goes into
+  `lemming artifact <id> <name> --file -`, not the entry.
+
+### Do not nest
+
+Never call `lemming run` or `lemming exec` from inside a task runner or a hook.
+Each level spawns another full agent against the same quota, and the inner loop
+competes with the outer one for the same tasks file. A runner that needs more
+work done adds tasks with `lemming add`; the running loop picks them up.
 
 ## What to know before running any of it
 

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lemming-cli"
-version = "0.6.1"
+version = "0.7.0"
 description = "An autonomous, iterative task runner for AI coding agents."
 readme = "README.md"
 authors = [

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/src/lemming/cli/operations.py

@@ -62,6 +62,23 @@ def quiet_poll_log_config() -> dict:
     is_flag=True,
     help="Do not auto-inject default flags (like --yolo) based on runner name.",
 )
+@click.option(
+    "--max-tasks",
+    type=click.IntRange(min=1),
+    help=(
+        "Stop between tasks once this many have completed or failed, so a "
+        "caller can drive the roadmap one milestone at a time."
+    ),
+)
+@click.option(
+    "--until",
+    "until_id",
+    metavar="TASK_ID",
+    help=(
+        "Stop between tasks once this task, or every task that replaced it, "
+        "has completed or failed. Accepts an unambiguous ID prefix."
+    ),
+)
 @click.argument("runner_args", nargs=-1, type=click.UNPROCESSED)
 @click.pass_context
 def run(
@@ -70,12 +87,24 @@ def run(
     yolo: bool,
     env: tuple,
     no_defaults: bool,
+    max_tasks: int | None,
+    until_id: str | None,
     runner_args: tuple,
 ) -> None:
     """Starts the orchestrator loop to autonomously execute pending tasks."""
     tasks_file = ctx.obj["TASKS_FILE"]
     verbose = ctx.obj["VERBOSE"]
 
+    # Resolve the milestone up front so a typo fails before any task runs.
+    until = None
+    if until_id:
+        try:
+            data = persistence.load_tasks(tasks_file)
+            until = queries.resolve_task(data.tasks, until_id).id
+        except (models.TaskNotFoundError, models.AmbiguousTaskIdError) as e:
+            click.echo(f"Error: {e}")
+            ctx.exit(1)
+
     # Determine the project's working directory
     working_dir = paths.get_working_dir(tasks_file)
 
@@ -111,6 +140,8 @@ def run(
             no_defaults,
             runner_args,
             working_dir=working_dir,
+            max_tasks=max_tasks,
+            until=until,
         )
     finally:
         persistence.release_loop_lock(tasks_file)

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/src/lemming/cli/operations_test.py

@@ -86,6 +86,53 @@ class TestCLIOperations(unittest.TestCase):
         self.assertEqual(result.exit_code, 1)
         self.assertIn("Another loop is already running", result.output)
 
+    def test_run_forwards_max_tasks(self):
+        with mock.patch.object(
+            operations, "run_loop", return_value=True
+        ) as run_loop:
+            result = self.cli_runner.invoke(
+                cli.cli, self.base_args + ["run", "--max-tasks", "2"]
+            )
+
+        self.assertEqual(result.exit_code, 0)
+        self.assertEqual(run_loop.call_args.kwargs["max_tasks"], 2)
+
+    def test_run_resolves_until_prefix(self):
+        persistence.save_tasks(
+            self.test_tasks_file,
+            models.Roadmap(
+                tasks=[models.Task(id="abcd1234", description="Milestone")]
+            ),
+        )
+
+        with mock.patch.object(
+            operations, "run_loop", return_value=True
+        ) as run_loop:
+            result = self.cli_runner.invoke(
+                cli.cli, self.base_args + ["run", "--until", "abcd"]
+            )
+
+        self.assertEqual(result.exit_code, 0)
+        self.assertEqual(run_loop.call_args.kwargs["until"], "abcd1234")
+
+    def test_run_rejects_unknown_until(self):
+        with mock.patch.object(operations, "run_loop") as run_loop:
+            result = self.cli_runner.invoke(
+                cli.cli, self.base_args + ["run", "--until", "nope"]
+            )
+
+        self.assertEqual(result.exit_code, 1)
+        self.assertIn("Task nope not found", result.output)
+        run_loop.assert_not_called()
+
+    def test_run_rejects_zero_max_tasks(self):
+        result = self.cli_runner.invoke(
+            cli.cli, self.base_args + ["run", "--max-tasks", "0"]
+        )
+
+        self.assertNotEqual(result.exit_code, 0)
+        self.assertIn("not in the range", result.output)
+
     def test_serve_help(self):
         result = self.cli_runner.invoke(cli.cli, ["serve", "--help"])
         self.assertEqual(result.exit_code, 0)

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/src/lemming/cli/tasks.py

@@ -106,7 +106,11 @@ def _echo_task_summary(
 @click.option(
     "--oneshot",
     is_flag=True,
-    help="Skip post-task orchestrator hooks when this task completes.",
+    help=(
+        "Skip post-task orchestrator hooks when this task completes. Use for "
+        "mechanical work (renames, typo fixes, version bumps, cleanups); each "
+        "hook is a full agent run."
+    ),
 )
 @click.pass_context
 def add(

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/src/lemming/orchestrator.py

@@ -516,6 +516,54 @@ def _handle_runner_exit(
     return False
 
 
+_SETTLED_STATUSES = frozenset(
+    {
+        models.TaskStatus.COMPLETED,
+        models.TaskStatus.FAILED,
+        models.TaskStatus.CANCELLED,
+        models.TaskStatus.SUPERSEDED,
+    }
+)
+
+
+def _task_settled(tasks_file: pathlib.Path, task_id: str) -> bool:
+    """Reports whether a task has reached a terminal status."""
+    data = persistence.load_tasks(tasks_file)
+    task = next((t for t in data.tasks if t.id == task_id), None)
+    return task is not None and task.status in _SETTLED_STATUSES
+
+
+def _count_pending(data: models.Roadmap) -> int:
+    return sum(t.status == models.TaskStatus.PENDING for t in data.tasks)
+
+
+def _report_task_limit(data: models.Roadmap, settled: int) -> None:
+    """Prints the one line a caller needs after a bounded run stops."""
+    task_label = "task" if settled == 1 else "tasks"
+    click.echo(
+        f"Stopped after {settled} {task_label}; {_count_pending(data)} pending."
+    )
+
+
+def _check_milestone(data: models.Roadmap, until: str) -> bool | None:
+    """Decides whether a milestone run should stop, reporting why.
+
+    Returns:
+        True to stop successfully, False to stop because the milestone task
+        vanished, None to keep running.
+    """
+    reached = queries.milestone_reached(data.tasks, until)
+    if reached is None:
+        click.echo(f"Milestone task {until} no longer exists; stopping.")
+        return False
+    if reached:
+        click.echo(
+            f"Reached milestone {until}; {_count_pending(data)} pending."
+        )
+        return True
+    return None
+
+
 def run_loop(
     tasks_file: pathlib.Path,
     verbose: bool,
@@ -527,6 +575,8 @@ def run_loop(
     hooks: list[str] | None = None,
     scope: str | None = None,
     once: bool = False,
+    max_tasks: int | None = None,
+    until: str | None = None,
 ) -> bool:
     """Runs pending tasks, returning True only when the roadmap is complete.
 
@@ -546,14 +596,22 @@ def run_loop(
         once: Run only the first task, through its configured attempt budget.
             Exhaustion leaves it pending, and failed finalization stops rather
             than turning a review placeholder back into runnable work.
+        max_tasks: Stop between tasks once this many have reached a terminal
+            status, so a caller can run the roadmap one milestone at a time.
+            Attempts that leave a task pending do not count.
+        until: Exact ID of a milestone task. Stop between tasks once it, or
+            every task that replaced it, has settled; stop unsuccessfully if
+            it is deleted.
 
     Returns:
-        True only when the roadmap ran to completion.
+        True when the roadmap ran to completion, the task limit was reached,
+        or the milestone was reached.
     """
     one_task_id = None
     one_task_config = None
     one_task_runner = None
     one_task_model = None
+    settled_count = 0
     while True:
         returncode = 0
 
@@ -567,6 +625,16 @@ def run_loop(
         # (e.g., from Web UI)
         data = persistence.load_tasks(tasks_file)
 
+        # Bounded runs stop between tasks, after hooks have settled the last
+        # one, so the caller sees a consistent roadmap.
+        if max_tasks is not None and settled_count >= max_tasks:
+            _report_task_limit(data, settled_count)
+            return True
+        if until is not None:
+            milestone = _check_milestone(data, until)
+            if milestone is not None:
+                return milestone
+
         retries = data.config.retries
         time_limit = data.config.time_limit
         runner_name = data.config.runner
@@ -663,6 +731,7 @@ def run_loop(
             )
             if should_abort:
                 return False
+            settled_count += _task_settled(tasks_file, task_id)
             continue
 
         # Add a small random jitter to avoid race conditions between
@@ -717,6 +786,7 @@ def run_loop(
                     (t for t in finalized.tasks if t.id == task_id), None
                 )
                 return bool(task and task.status == models.TaskStatus.COMPLETED)
+            settled_count += _task_settled(tasks_file, task_id)
             continue
 
         prompt = prompts.prepare_prompt(
@@ -822,6 +892,7 @@ def run_loop(
         )
         if should_abort:
             return False
+        settled_count += _task_settled(tasks_file, task_id)
 
         if once:
             updated = persistence.load_tasks(tasks_file)

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/src/lemming/orchestrator_test.py

@@ -1053,6 +1053,151 @@ def test_run_hooks_reloads_tasks(mock_run, mock_prepare, hooks_env):
         assert mock_load.call_count == 5
 
 
+def _complete_current_task(tasks_file):
+    """Builds a runner stub that marks whichever task it runs as completed."""
+
+    def side_effect(cmd, tasks_file_arg, task_id, *args, **kwargs):
+        with persistence.lock_tasks(tasks_file):
+            data = persistence.load_tasks(tasks_file)
+            task = next(t for t in data.tasks if t.id == task_id)
+            task.status = models.TaskStatus.COMPLETED
+            task.completed_at = time.time()
+            persistence.save_tasks(tasks_file, data)
+        return (0, "output", "")
+
+    return side_effect
+
+
+@mock.patch("lemming.runner.run_with_heartbeat")
+def test_run_loop_max_tasks_stops_between_tasks(mock_run, setup_env, capsys):
+    """A milestone limit exits cleanly and leaves the queue intact."""
+    test_tasks_file, _ = setup_env
+    operations.add_task(test_tasks_file, "Task 2")
+    operations.add_task(test_tasks_file, "Task 3")
+    mock_run.side_effect = _complete_current_task(test_tasks_file)
+
+    completed = run_loop(
+        test_tasks_file,
+        verbose=False,
+        retry_delay=0,
+        yolo=True,
+        no_defaults=False,
+        runner_args=(),
+        hooks=[],
+        max_tasks=2,
+    )
+
+    assert completed is True
+    statuses = [t.status for t in persistence.load_tasks(test_tasks_file).tasks]
+    assert statuses == [
+        models.TaskStatus.COMPLETED,
+        models.TaskStatus.COMPLETED,
+        models.TaskStatus.PENDING,
+    ]
+    assert "Stopped after 2 tasks; 1 pending" in capsys.readouterr().out
+
+
+@mock.patch("lemming.runner.run_with_heartbeat")
+def test_run_loop_max_tasks_counts_only_settled_tasks(
+    mock_run, setup_env, capsys
+):
+    """An attempt that leaves the task pending does not consume the budget."""
+    test_tasks_file, _ = setup_env
+    operations.add_task(test_tasks_file, "Task 2")
+    attempts = []
+
+    def flaky_then_complete(cmd, tasks_file_arg, task_id, *args, **kwargs):
+        attempts.append(task_id)
+        if len(attempts) == 1:
+            return (0, "no completion reported", "")
+        return _complete_current_task(test_tasks_file)(
+            cmd, tasks_file_arg, task_id, *args, **kwargs
+        )
+
+    mock_run.side_effect = flaky_then_complete
+
+    completed = run_loop(
+        test_tasks_file,
+        verbose=False,
+        retry_delay=0,
+        yolo=True,
+        no_defaults=False,
+        runner_args=(),
+        hooks=[],
+        max_tasks=1,
+    )
+
+    assert completed is True
+    assert attempts == ["task1", "task1"]
+    statuses = [t.status for t in persistence.load_tasks(test_tasks_file).tasks]
+    assert statuses == [models.TaskStatus.COMPLETED, models.TaskStatus.PENDING]
+
+
+@mock.patch("lemming.runner.run_with_heartbeat")
+def test_run_loop_until_stops_after_milestone_task(mock_run, setup_env, capsys):
+    """The loop runs inserted tasks and stops once the target settles."""
+    test_tasks_file, _ = setup_env
+    milestone = operations.add_task(test_tasks_file, "Milestone")
+    operations.add_task(test_tasks_file, "After milestone")
+    mock_run.side_effect = _complete_current_task(test_tasks_file)
+
+    completed = run_loop(
+        test_tasks_file,
+        verbose=False,
+        retry_delay=0,
+        yolo=True,
+        no_defaults=False,
+        runner_args=(),
+        hooks=[],
+        until=milestone.id,
+    )
+
+    assert completed is True
+    statuses = [t.status for t in persistence.load_tasks(test_tasks_file).tasks]
+    assert statuses == [
+        models.TaskStatus.COMPLETED,
+        models.TaskStatus.COMPLETED,
+        models.TaskStatus.PENDING,
+    ]
+    assert f"Reached milestone {milestone.id}; 1 pending" in (
+        capsys.readouterr().out
+    )
+
+
+@mock.patch("lemming.runner.run_with_heartbeat")
+def test_run_loop_until_stops_when_milestone_task_vanishes(
+    mock_run, setup_env, capsys
+):
+    """Deleting the target mid-run is reported instead of running the queue."""
+    test_tasks_file, _ = setup_env
+    milestone = operations.add_task(test_tasks_file, "Milestone")
+
+    def complete_and_delete(cmd, tasks_file_arg, task_id, *args, **kwargs):
+        operations.delete_tasks(test_tasks_file, milestone.id)
+        return _complete_current_task(test_tasks_file)(
+            cmd, tasks_file_arg, task_id, *args, **kwargs
+        )
+
+    mock_run.side_effect = complete_and_delete
+
+    completed = run_loop(
+        test_tasks_file,
+        verbose=False,
+        retry_delay=0,
+        yolo=True,
+        no_defaults=False,
+        runner_args=(),
+        hooks=[],
+        until=milestone.id,
+    )
+
+    assert completed is False
+    assert mock_run.call_count == 1
+    assert f"Milestone task {milestone.id} no longer exists" in (
+        capsys.readouterr().out
+    )
+
+
 @mock.patch("lemming.runner.run_with_heartbeat")
 def test_run_loop_records_resolved_command(mock_run, setup_env):
     """Provenance is persisted so the model behind a commit is recoverable."""

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/src/lemming/prompts/hooks/90-roadmap.md

@@ -62,6 +62,12 @@ the plan up-to-date with minimal friction.
     Include the concrete files, symbols, motivation, and acceptance criteria the
     task needs, but do not repeat project-wide rules already present in the
     long-term goal.
+    **Mechanical tasks MUST be added with `--oneshot`**: cleanups, renames,
+    typo fixes, version bumps, deleting scratch files, applying formatter
+    output, and the follow-ups from directive 7. Every hook that runs after
+    such a task costs a full agent run, often longer than the task itself.
+    Reserve hooked tasks for work that changes behavior. Mark existing
+    mechanical tasks with `edit <id> --oneshot` when you notice them.
 9.  **No Code Changes**: Your only persistent changes may be to the roadmap via
     the `lemming` CLI. Do NOT edit source or configuration files. Reading the
     workspace and running existing build, test, and entry-point commands for
@@ -76,10 +82,10 @@ the plan up-to-date with minimal friction.
 ## Commands
 
 ```bash
-# Add new tasks
-lemming --tasks-file {{tasks_file_path}} add '<description>' [--index N]
+# Add new tasks (--oneshot for mechanical work, see directive 8)
+lemming --tasks-file {{tasks_file_path}} add '<description>' [--index N] [--oneshot]
 # Edit existing tasks
-lemming --tasks-file {{tasks_file_path}} edit <id> --description '<desc>'
+lemming --tasks-file {{tasks_file_path}} edit <id> --description '<desc>' [--oneshot]
 # Reset/Delete/Supersede/Status
 lemming --tasks-file {{tasks_file_path}} reset <id>
 lemming --tasks-file {{tasks_file_path}} delete <id>

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/src/lemming/prompts/taskrunner.md

@@ -41,6 +41,10 @@ Your CURRENT, EXCLUSIVE task is: **{{description}}**
      Include the file paths, symbols, motivation, and acceptance criteria that
      task needs, but do not restate project-wide rules already present in the
      long-term goal.
+   - **Mechanical Tasks Are Oneshot:** Add cleanups, renames, typo fixes,
+     version bumps, and scratch-file removal with `add ... --oneshot`. Each
+     post-task hook is a full agent run, so a hooked mechanical task takes
+     several times longer than it should.
    - **Detailed Evidence:** Never paste verbose gate output, transcripts, or
      error traces into a description or progress entry. Store them out of band:
      `lemming --tasks-file {{tasks_file_path}} artifact {{task_id}} <name> --file - --note '<one line>'`

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/src/lemming/tasks/queries.py

@@ -187,3 +187,30 @@ def get_pending_task(data: models.Roadmap) -> models.Task | None:
 
     uncompleted.sort(key=sort_key)
     return uncompleted[0]
+
+
+def milestone_reached(tasks: list[models.Task], task_id: str) -> bool | None:
+    """Reports whether a task, or everything that replaced it, has settled.
+
+    A superseded task counts as reached only once every replacement recorded
+    against it has settled too, so a milestone survives the roadmap hook
+    splitting it into smaller tasks.
+
+    Args:
+        tasks: Every task in the roadmap.
+        task_id: Exact ID of the milestone task.
+
+    Returns:
+        True when reached, False while work remains, None if the task no
+        longer exists.
+    """
+    task = next((t for t in tasks if t.id == task_id), None)
+    if task is None:
+        return None
+    if task.status == models.TaskStatus.SUPERSEDED:
+        replacements = [t for t in tasks if t.parent == task_id]
+        return all(milestone_reached(tasks, t.id) for t in replacements)
+    return task.status not in (
+        models.TaskStatus.PENDING,
+        models.TaskStatus.IN_PROGRESS,
+    )

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/src/lemming/tasks/queries_test.py

@@ -254,3 +254,39 @@ def test_get_pending_task_none_if_in_progress(tmp_path):
         )
         pending = queries.get_pending_task(data)
         assert pending is None
+
+
+def _task(task_id, status, parent=None):
+    return models.Task(
+        id=task_id, description=task_id, status=status, parent=parent
+    )
+
+
+def test_milestone_reached_follows_terminal_status():
+    tasks = [_task("a", models.TaskStatus.PENDING)]
+    assert queries.milestone_reached(tasks, "a") is False
+
+    tasks = [_task("a", models.TaskStatus.FAILED)]
+    assert queries.milestone_reached(tasks, "a") is True
+
+
+def test_milestone_reached_waits_for_replacements():
+    tasks = [
+        _task("a", models.TaskStatus.SUPERSEDED),
+        _task("b", models.TaskStatus.COMPLETED, parent="a"),
+        _task("c", models.TaskStatus.SUPERSEDED, parent="a"),
+        _task("d", models.TaskStatus.PENDING, parent="c"),
+    ]
+    assert queries.milestone_reached(tasks, "a") is False
+
+    tasks[3].status = models.TaskStatus.COMPLETED
+    assert queries.milestone_reached(tasks, "a") is True
+
+
+def test_milestone_reached_treats_dropped_task_as_reached():
+    tasks = [_task("a", models.TaskStatus.SUPERSEDED)]
+    assert queries.milestone_reached(tasks, "a") is True
+
+
+def test_milestone_reached_reports_missing_task():
+    assert queries.milestone_reached([], "a") is None

{lemming_cli-0.6.1 → lemming_cli-0.7.0}/uv.lock

@@ -154,7 +154,7 @@ wheels = [
 
 [[package]]
 name = "lemming-cli"
-version = "0.6.1"
+version = "0.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },