lemming-cli 0.1.1__tar.gz → 0.1.3__tar.gz

lemming_cli-0.1.3/.github/workflows/screenshots.yml

@@ -0,0 +1,51 @@
+name: Screenshots
+
+# Regenerates the dashboard screenshots in docs/ whenever the web UI changes,
+# so they can never go stale. Generation is deterministic (frozen clock and
+# animations disabled), so this only commits when the UI actually changed.
+# The commit touches only docs/screenshots, which is outside the paths filter
+# below, so it cannot re-trigger this workflow.
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/lemming/web/**'
+      - 'playwright.config.js'
+      - '.github/workflows/screenshots.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  regenerate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+
+      - name: Install Node.js dependencies
+        run: npm install
+
+      - name: Install Playwright browser
+        run: npx playwright install --with-deps chromium
+
+      - name: Regenerate screenshots
+        run: npm run screenshots
+
+      - name: Commit updated screenshots
+        run: |
+          if git diff --quiet docs/screenshots; then
+            echo "Screenshots are up to date."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add docs/screenshots
+          git commit -m "Regenerate dashboard screenshots"
+          git pull --rebase --autostash origin main
+          git push

{lemming_cli-0.1.1 → lemming_cli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lemming-cli
-Version: 0.1.1
+Version: 0.1.3
 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
@@ -32,7 +32,7 @@ human-readable `tasks.yml` file.
 ## Why Lemming?
 
 - **Zero Context Drift**: By breaking projects into discrete tasks, Lemming
-  ensures agents stay focused. They only see the project context, relevant
+  ensures agents stay focused. They only see the long-term goal, relevant
   history, and the specific task at hand.
 - **Transparency & Control**: Every decision, technical finding, and progress
   update is recorded in a human-readable `tasks.yml` file. You can step in,
@@ -61,11 +61,11 @@ uv tool install lemming-cli
 
 ### 1. Scaffold the Roadmap
 
-Initialize your project context and define your goals.
+Set the long-term goal and define the first tasks.
 
 ```bash
-# Set project-wide rules (e.g. tech stack, style guides)
-lemming context "Use React, TypeScript, and Tailwind. Follow TDD."
+# Set the long-term goal that every task works toward
+lemming goal "Build a habit-tracking web app with auth, offline support, and tests"
 
 # Add tasks to the queue
 lemming add "Initialize the project with Vite"
@@ -73,6 +73,11 @@ lemming add "Create the Button component"
 lemming add "Implement the authentication flow"
 ```
 
+The goal is the one piece of state every task sees, no matter how far into the
+roadmap it runs — describe what "done" looks like for the project. Durable
+coding rules (tech stack, style guides) belong in your repo's agent files (e.g.
+`AGENTS.md`, `CLAUDE.md`), which your agent already reads on its own.
+
 ### 2. Review and Refine
 
 See exactly what's pending and what the agent will see.
@@ -114,19 +119,19 @@ lemming serve --tunnel cloudflare
   folders directly from the UI.
 - **Browse Files**: Quickly open your workspace in a separate window to inspect
   files and directory structure alongside the roadmap.
-- **Interactive Controls**: Add tasks, edit context, and manage the execution
+- **Interactive Controls**: Add tasks, edit the goal, and manage the execution
   loop from your browser.
 
 ---
 
 ## How it Works
 
-Lemming maintains a human-readable `tasks.yml` file containing your project
-context, a queue of tasks, and recorded progress. When you run `lemming run`, it
+Lemming maintains a human-readable `tasks.yml` file containing your long-term
+goal, a queue of tasks, and recorded progress. When you run `lemming run`, it
 loops through each pending task:
 
 1.  **Build a scoped prompt**: Lemming assembles a prompt containing only the
-    project context, a summary of completed tasks and their progress, and the
+    long-term goal, a summary of completed tasks and their progress, and the
     current task description.
 2.  **Invoke the agent**: It launches your chosen agent CLI with that prompt,
     monitors it with heartbeats, and streams output to a log file.
@@ -153,19 +158,24 @@ tasks may not fully achieve the stated goal. **Orchestrator Hooks** address this
 by running custom agents or scripts after each task execution to evaluate
 results and adapt the roadmap.
 
-By default, Lemming runs all available hooks (including the built-in `roadmap`
-hook). You can customize this behavior via the `hooks` subcommand:
+Lemming runs every hook it discovers on the filesystem (including the
+built-in `roadmap` hook). Hooks are plain Markdown files, and udev-style
+filename conventions control their behavior:
 
-```bash
-# Enable or disable hooks for the project
-lemming hooks enable lint
-lemming hooks disable roadmap
+- **Ordering**: A numeric prefix sets the execution order (e.g.
+  `10-lint.md` runs before `90-roadmap.md`); files without a prefix
+  default to priority 50.
+- **Failure hooks**: Hooks at priority 90 and above also run when a task
+  fails; all others only run on success.
+- **Disabling**: An empty file masks (disables) the hook of the same name
+  from a lower-precedence layer.
 
-# Set the exact list of active hooks
-lemming hooks set roadmap lint
+```bash
+# Disable a hook for this project (writes an empty .lemming/hooks/50-lint.md)
+lemming hooks disable lint
 
-# Reset to default (run all available hooks)
-lemming hooks reset
+# Re-enable it (removes the mask file)
+lemming hooks enable lint
 ```
 
 ### Built-in Hooks ⚓️
@@ -189,33 +199,41 @@ You can create your own hooks by adding Markdown files to:
 1.  **Project-specific**: `.lemming/hooks/*.md`
 2.  **Global**: `~/.local/lemming/hooks/*.md`
 
-Lemming's built-in hooks can be symlinked to the global directory using
-`lemming hooks install`. This allows you to easily **override** a built-in hook
-by replacing its symlink with a file, or **disable** a global override by
-deleting the symlink.
+To **override** a built-in hook, create a file with the same logical name
+(the numeric prefix is not part of the name, so `20-roadmap.md` overrides
+the built-in `90-roadmap.md` and also moves it to priority 20); delete the
+file to restore the built-in version.
 
 Hooks follow a specific discovery precedence: **Project > Global > Built-in**.
-See [DOCS/HOOKS.md](docs/HOOKS.md) for more details.
+See [docs/HOOKS.md](docs/HOOKS.md) for more details.
 
 ### Managing Hooks and Configuration
 
 Use the `config` and `hooks` commands to manage your project's execution loop:
 
 ```bash
-# List all available hooks (built-in and local)
+# List all hooks in execution order, with source and status
 lemming hooks list
 
-# Install (symlink) built-in hooks to the global directory
-lemming hooks install
-
-# View current project configuration
+# View current project configuration (includes the active hooks)
 lemming config list
 
 # Persist configuration to tasks.yml
 lemming config set runner aider
-lemming hooks set roadmap lint
 ```
 
+### Evaluating Prompt Changes
+
+Editing a hook prompt can regress behavior without any test failing. The
+containerized eval harness replays realistic scenarios against the real hook
+execution path and grades the outcome mechanically:
+
+```bash
+uv run python -m lemming.evals run --suite roadmap
+```
+
+See [docs/EVALS.md](docs/EVALS.md) for details.
+
 ---
 
 ## Command Reference
@@ -223,8 +241,8 @@ lemming hooks set roadmap lint
 ### Roadmap Management
 
 - **`status [<id>]`**: Roadmap overview or deep-dive into a specific task.
-- **`context [<text>]`**: Set or view project-wide instructions. Supports
-  `-f/--file`.
+- **`goal [<text>]`**: Set or view the long-term goal shared by all tasks.
+  Supports `-f/--file`.
 - **`add <desc>`**: Append a new task. Supports `--index` and `--runner`.
 - **`edit <id>`**: Modify a task's description, runner, or position.
 - **`delete <id>`**: Remove a task. Supports `--all` and `--completed` for bulk
@@ -321,6 +339,10 @@ git push origin v0.1.1
 
 ## Screenshots
 
+These are regenerated automatically by CI whenever the web UI changes (see
+`.github/workflows/screenshots.yml`); run `npm run screenshots` to preview them
+locally.
+
 ### Dashboard
 
 ![Dashboard](docs/screenshots/dashboard-desktop.png)

{lemming_cli-0.1.1 → lemming_cli-0.1.3}/README.md

@@ -10,7 +10,7 @@ human-readable `tasks.yml` file.
 ## Why Lemming?
 
 - **Zero Context Drift**: By breaking projects into discrete tasks, Lemming
-  ensures agents stay focused. They only see the project context, relevant
+  ensures agents stay focused. They only see the long-term goal, relevant
   history, and the specific task at hand.
 - **Transparency & Control**: Every decision, technical finding, and progress
   update is recorded in a human-readable `tasks.yml` file. You can step in,
@@ -39,11 +39,11 @@ uv tool install lemming-cli
 
 ### 1. Scaffold the Roadmap
 
-Initialize your project context and define your goals.
+Set the long-term goal and define the first tasks.
 
 ```bash
-# Set project-wide rules (e.g. tech stack, style guides)
-lemming context "Use React, TypeScript, and Tailwind. Follow TDD."
+# Set the long-term goal that every task works toward
+lemming goal "Build a habit-tracking web app with auth, offline support, and tests"
 
 # Add tasks to the queue
 lemming add "Initialize the project with Vite"
@@ -51,6 +51,11 @@ lemming add "Create the Button component"
 lemming add "Implement the authentication flow"
 ```
 
+The goal is the one piece of state every task sees, no matter how far into the
+roadmap it runs — describe what "done" looks like for the project. Durable
+coding rules (tech stack, style guides) belong in your repo's agent files (e.g.
+`AGENTS.md`, `CLAUDE.md`), which your agent already reads on its own.
+
 ### 2. Review and Refine
 
 See exactly what's pending and what the agent will see.
@@ -92,19 +97,19 @@ lemming serve --tunnel cloudflare
   folders directly from the UI.
 - **Browse Files**: Quickly open your workspace in a separate window to inspect
   files and directory structure alongside the roadmap.
-- **Interactive Controls**: Add tasks, edit context, and manage the execution
+- **Interactive Controls**: Add tasks, edit the goal, and manage the execution
   loop from your browser.
 
 ---
 
 ## How it Works
 
-Lemming maintains a human-readable `tasks.yml` file containing your project
-context, a queue of tasks, and recorded progress. When you run `lemming run`, it
+Lemming maintains a human-readable `tasks.yml` file containing your long-term
+goal, a queue of tasks, and recorded progress. When you run `lemming run`, it
 loops through each pending task:
 
 1.  **Build a scoped prompt**: Lemming assembles a prompt containing only the
-    project context, a summary of completed tasks and their progress, and the
+    long-term goal, a summary of completed tasks and their progress, and the
     current task description.
 2.  **Invoke the agent**: It launches your chosen agent CLI with that prompt,
     monitors it with heartbeats, and streams output to a log file.
@@ -131,19 +136,24 @@ tasks may not fully achieve the stated goal. **Orchestrator Hooks** address this
 by running custom agents or scripts after each task execution to evaluate
 results and adapt the roadmap.
 
-By default, Lemming runs all available hooks (including the built-in `roadmap`
-hook). You can customize this behavior via the `hooks` subcommand:
+Lemming runs every hook it discovers on the filesystem (including the
+built-in `roadmap` hook). Hooks are plain Markdown files, and udev-style
+filename conventions control their behavior:
 
-```bash
-# Enable or disable hooks for the project
-lemming hooks enable lint
-lemming hooks disable roadmap
+- **Ordering**: A numeric prefix sets the execution order (e.g.
+  `10-lint.md` runs before `90-roadmap.md`); files without a prefix
+  default to priority 50.
+- **Failure hooks**: Hooks at priority 90 and above also run when a task
+  fails; all others only run on success.
+- **Disabling**: An empty file masks (disables) the hook of the same name
+  from a lower-precedence layer.
 
-# Set the exact list of active hooks
-lemming hooks set roadmap lint
+```bash
+# Disable a hook for this project (writes an empty .lemming/hooks/50-lint.md)
+lemming hooks disable lint
 
-# Reset to default (run all available hooks)
-lemming hooks reset
+# Re-enable it (removes the mask file)
+lemming hooks enable lint
 ```
 
 ### Built-in Hooks ⚓️
@@ -167,33 +177,41 @@ You can create your own hooks by adding Markdown files to:
 1.  **Project-specific**: `.lemming/hooks/*.md`
 2.  **Global**: `~/.local/lemming/hooks/*.md`
 
-Lemming's built-in hooks can be symlinked to the global directory using
-`lemming hooks install`. This allows you to easily **override** a built-in hook
-by replacing its symlink with a file, or **disable** a global override by
-deleting the symlink.
+To **override** a built-in hook, create a file with the same logical name
+(the numeric prefix is not part of the name, so `20-roadmap.md` overrides
+the built-in `90-roadmap.md` and also moves it to priority 20); delete the
+file to restore the built-in version.
 
 Hooks follow a specific discovery precedence: **Project > Global > Built-in**.
-See [DOCS/HOOKS.md](docs/HOOKS.md) for more details.
+See [docs/HOOKS.md](docs/HOOKS.md) for more details.
 
 ### Managing Hooks and Configuration
 
 Use the `config` and `hooks` commands to manage your project's execution loop:
 
 ```bash
-# List all available hooks (built-in and local)
+# List all hooks in execution order, with source and status
 lemming hooks list
 
-# Install (symlink) built-in hooks to the global directory
-lemming hooks install
-
-# View current project configuration
+# View current project configuration (includes the active hooks)
 lemming config list
 
 # Persist configuration to tasks.yml
 lemming config set runner aider
-lemming hooks set roadmap lint
 ```
 
+### Evaluating Prompt Changes
+
+Editing a hook prompt can regress behavior without any test failing. The
+containerized eval harness replays realistic scenarios against the real hook
+execution path and grades the outcome mechanically:
+
+```bash
+uv run python -m lemming.evals run --suite roadmap
+```
+
+See [docs/EVALS.md](docs/EVALS.md) for details.
+
 ---
 
 ## Command Reference
@@ -201,8 +219,8 @@ lemming hooks set roadmap lint
 ### Roadmap Management
 
 - **`status [<id>]`**: Roadmap overview or deep-dive into a specific task.
-- **`context [<text>]`**: Set or view project-wide instructions. Supports
-  `-f/--file`.
+- **`goal [<text>]`**: Set or view the long-term goal shared by all tasks.
+  Supports `-f/--file`.
 - **`add <desc>`**: Append a new task. Supports `--index` and `--runner`.
 - **`edit <id>`**: Modify a task's description, runner, or position.
 - **`delete <id>`**: Remove a task. Supports `--all` and `--completed` for bulk
@@ -299,6 +317,10 @@ git push origin v0.1.1
 
 ## Screenshots
 
+These are regenerated automatically by CI whenever the web UI changes (see
+`.github/workflows/screenshots.yml`); run `npm run screenshots` to preview them
+locally.
+
 ### Dashboard
 
 ![Dashboard](docs/screenshots/dashboard-desktop.png)

lemming_cli-0.1.3/docs/EVALS.md

@@ -0,0 +1,89 @@
+# Prompt Evals 🧪
+
+Lemming's behavior is driven by prompts (the task runner and the orchestrator
+hooks), so a prompt edit can regress the system without any test failing. The
+eval harness in `lemming.evals` catches that: it replays realistic "a task just
+finished" situations against the real hook execution path and grades the outcome
+with mechanical checks — no LLM judging involved.
+
+## How it Works
+
+Each **scenario** seeds a hermetic fixture: a tiny git repository plus a
+`tasks.yml` mid-flight (e.g. a task that just failed for the third time). A
+**trial** runs the hook under eval against that fixture using the same code path
+as the orchestrator, then a **grader** inspects the aftermath:
+
+- Did the roadmap hook repair a task that failed at max attempts, or did it
+  naively reset it?
+- Did it leave a healthy roadmap untouched?
+- Did it keep its hands off source files (`git status` must stay clean)?
+
+Every trial runs in its own container built from the repo `Dockerfile`, with
+only the fixture workspace and a per-trial `LEMMING_HOME` mounted. The agent
+under eval cannot touch the host, and concurrent trials share no state, so
+trials run in parallel safely.
+
+## Running
+
+Evals invoke real agents: expect minutes of wall clock and real token spend.
+They are a manual gate for prompt changes, not part of the unit test suite.
+
+```bash
+# List available suites and scenarios
+uv run python -m lemming.evals list
+
+# Run a suite (roadmap or readability): scenarios x 3 trials in parallel
+uv run python -m lemming.evals run --suite roadmap
+uv run python -m lemming.evals run --suite readability
+
+# Iterate on a single scenario with fewer trials
+uv run python -m lemming.evals run \
+    --scenario repair-exhausted-failure --trials 1 --skip-build
+
+# Machine-readable results and a non-default pass threshold
+uv run python -m lemming.evals run --json-report report.json --min-pass-rate 0.67
+```
+
+The command prints per-scenario pass rates (agents are stochastic, so think in
+rates, not booleans) and, for each failed trial, the failing checks plus the
+kept workspace path so you can inspect exactly what the agent did. Runner logs
+land in the trial's `home/` directory next to the workspace. The exit code is
+non-zero when any scenario's pass rate drops below `--min-pass-rate`.
+
+### Required vs Advisory Checks
+
+Most checks encode the prompt's hard contract mechanically (no source changes,
+no naive task resets, tests stay green) — a red there is a defect, and the right
+response is to improve the prompt. A few checks grade a semantic property
+through a keyword proxy (e.g. "the added task mentions multiply") and are marked
+**advisory**: they never fail a trial and print as yellow `inspect:` lines
+instead. An advisory red means read the workspace and adjudicate — if the
+agent's output was genuinely fine, widen the proxy; if it was vague, tighten the
+prompt. Keeping proxies out of the pass/fail gate is what keeps hard reds
+trustworthy.
+
+### Credentials
+
+The default runner is `agy`. Each trial automatically receives a private,
+disposable copy of the host's `~/.gemini` config (caches, history, and the
+bundled CLI excluded) mounted at `/root/.gemini`, so containers can refresh
+tokens and write state without ever touching the real agy home — and concurrent
+trials stay fully isolated from each other.
+
+For API-key runners, `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`,
+`GEMINI_API_KEY`, and `GOOGLE_API_KEY` are forwarded into the container when set
+on the host. Any other credential files can be mounted with `--volume`.
+
+## Adding Scenarios
+
+Scenarios live in `src/lemming/evals/` (see `roadmap.py`):
+
+1. Write a `build` function that seeds the workspace via `fixtures.init_repo`
+   and `fixtures.save_roadmap`.
+2. Write a `grade` function returning `scenarios.Check` results. Prefer checks
+   that are mechanically verifiable: roadmap diffs, `fixtures.dirty_paths` for
+   source drift, task statuses.
+3. Register the scenario in the module's `SCENARIOS` list, and new suites in
+   `suites.all_suites`.
+4. Add unit tests that grade simulated good and bad agent behavior; the graders
+   themselves must stay fast and offline.

lemming_cli-0.1.3/docs/HOOKS.md

@@ -0,0 +1,164 @@
+# Orchestrator Hooks ⚓️
+
+Orchestrator hooks are a powerful way to extend the Lemming workflow. They allow
+you to execute custom agents or scripts after each task, enabling automated
+roadmap revision, code quality checks, or any other post-task validation.
+
+## How it Works
+
+When a task finishes (whether it succeeded or failed), Lemming can run one or
+more **orchestrator hooks**. Each hook:
+
+1.  **Loads a prompt template**: Lemming looks for a `.md` file corresponding to
+    the hook name.
+2.  **Renders the prompt**: It injects context about the current roadmap and the
+    task that just finished.
+3.  **Invokes an agent**: It runs your configured runner with the rendered
+    prompt.
+4.  **Captures the output**: The agent's output is appended to the task's
+    execution log, and any commands it runs (e.g. `lemming add`, `lemming edit`)
+    are executed against the roadmap.
+
+## Naming Convention
+
+Hooks are Markdown files discovered from the filesystem, and udev-style
+filename conventions control their behavior:
+
+- **Ordering**: A numeric prefix determines execution order: `10-lint.md`
+  runs before `90-roadmap.md`. Files without a prefix default to priority
+  50. The prefix is **not** part of the hook's name: `90-roadmap.md`
+  defines the hook `roadmap`.
+- **Failure hooks**: Hooks at priority 90 and above also run when a task
+  fails. All other hooks only run after successful tasks. The built-in
+  `roadmap` hook ships as `90-roadmap.md` so it can react to failures.
+- **Masking**: An empty file disables the hook of the same name from a
+  lower-precedence layer (see below). For example, an empty
+  `.lemming/hooks/readability.md` disables the built-in `readability` hook
+  for that project.
+- **Overriding**: A non-empty file replaces the hook of the same name from
+  a lower-precedence layer. The winning filename also determines the
+  priority, so keep the `9x-` prefix when overriding a failure hook (e.g.
+  `90-roadmap.md`), or use a different prefix to deliberately reorder it.
+
+## Built-in Hooks
+
+### `roadmap` (Default)
+
+The primary mechanism for autonomous project management. It analyzes the results
+of the finished task and decides if the remaining roadmap needs to be adjusted
+(e.g., adding a missing prerequisite, skipping obsolete tasks, or breaking down
+a broad task).
+
+### `readability`
+
+A code quality hook that reviews changes for adherence to the Google Style Guide
+and general readability using the bundled `lemming readability` tool. It
+provides feedback via task progress or suggests follow-up refactoring tasks.
+
+### Editing Built-in Hook Prompts
+
+The built-in hook prompts are load-bearing: a wording change can regress
+orchestration behavior without any unit test failing. When you edit a prompt
+under `src/lemming/prompts/hooks/`, run its eval suite before shipping:
+
+```bash
+uv run python -m lemming.evals run --suite roadmap
+uv run python -m lemming.evals run --suite readability
+```
+
+See [EVALS.md](EVALS.md) for how the suites work and how to interpret results.
+
+## Custom Hooks
+
+You can define your own hooks by creating Markdown files in the following
+locations:
+
+1.  `.lemming/hooks/{name}.md` (Project-specific hooks)
+2.  `~/.local/lemming/hooks/{name}.md` (Global hooks)
+
+### Precedence
+
+When Lemming looks for a hook, it resolves each logical name through the
+following layers, highest precedence first:
+
+1.  **Project-specific**: `.lemming/hooks/`
+2.  **Global**: `~/.local/lemming/hooks/`
+3.  **Built-in**: Bundled with the Lemming package.
+
+Because of this precedence order, overriding a built-in hook only requires
+creating a Markdown file with the same logical name in the project or global
+directory (e.g. `~/.local/lemming/hooks/90-roadmap.md`); delete the file to
+restore the built-in version. Global hooks are available to all Lemming
+projects on the system.
+
+### Example: `lint` hook
+
+Create `.lemming/hooks/lint.md`:
+
+```markdown
+You are a code quality orchestrator. A task has just finished. Review the files
+changed in this task and ensure they follow the project's style guide. If there
+are issues, add a new task to fix them.
+
+### Roadmap Context
+
+{{roadmap}}
+
+### Finished Task
+
+{{finished_task}}
+```
+
+## Using Hooks
+
+### Enabling and Disabling
+
+Lemming runs every hook it discovers that is not masked. There is no hook
+configuration in `tasks.yml`; the filesystem is the single source of truth.
+
+The `hooks` command group provides shortcuts for managing project masks:
+
+```bash
+# Disable a hook for this project (writes an empty .lemming/hooks/50-lint.md)
+lemming hooks disable lint
+
+# Re-enable it (removes the mask file)
+lemming hooks enable lint
+```
+
+These commands validate the hook names before changing anything and refuse
+to touch files with content (a non-empty file is an override, not a mask).
+An empty file created by hand works just as well; the commands additionally
+keep the hook's priority in the mask filename so listings stay accurate.
+
+Hooks are re-discovered on every task execution, so changes are picked up
+dynamically by a running orchestrator loop.
+
+### Available Variables
+
+Your hook template can use the following placeholders:
+
+- `{{roadmap}}`: A structured summary of the long-term goal and all tasks.
+- `{{finished_task}}`: Details about the task that just finished (ID,
+  description, progress, and the last 100 lines of its execution log).
+- `{{finished_task_id}}`: The ID of the task that just finished.
+- `{{tasks_file_name}}`: The filename of the tasks YAML file.
+- `{{tasks_file_path}}`: The full path to the tasks YAML file.
+
+## Developer Ergonomics
+
+### Listing Hooks
+
+You can see all hooks in execution order, with their priority, source layer,
+and status (disabled, runs on failure) using the CLI:
+
+```bash
+lemming hooks list
+```
+
+### Runner Selection
+
+Hooks always use the same runner as your tasks. This ensures consistency and
+simplifies configuration. Command-line arguments passed after `--` are
+automatically forwarded to both the main task execution and any subsequent
+hooks.