repoactive 0.2.4.dev2__tar.gz → 0.2.5.dev1__tar.gz

{repoactive-0.2.4.dev2 → repoactive-0.2.5.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repoactive
-Version: 0.2.4.dev2
+Version: 0.2.5.dev1
 Summary: Script-driven code changes with automated merge requests
 License-Expression: GPL-3.0-or-later
 License-File: LICENSE
@@ -37,10 +37,11 @@ and (with `--mode publish`) the full MR lifecycle.
 
 ## Contents
 
+- [Use cases](#use-cases)
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [How it works](#how-it-works)
-- [Use cases](#use-cases)
+  - [Keeping the local clone current](#keeping-the-local-clone-current)
 - [Usage](#usage)
   - [Environment variables](#environment-variables)
 - [Inspecting repoactive commits](#inspecting-repoactive-commits)
@@ -48,13 +49,35 @@ and (with `--mode publish`) the full MR lifecycle.
 - [Listing jobs](#listing-jobs)
 - [Listing tags](#listing-tags)
 - [Configuration](#configuration)
+  - [`[job-defaults]`](#job-defaults)
+  - [`[job.<name>]`](#jobname)
+  - [Stacking MRs](#stacking-mrs)
+  - [Example](#example)
+  - [`[platform.<name>]`](#platformname)
+  - [Config file locations](#config-file-locations)
+  - [Overriding values on the command line](#overriding-values-on-the-command-line)
 - [Selecting jobs with tags](#selecting-jobs-with-tags)
+  - [Keeping unmerged branches current](#keeping-unmerged-branches-current)
 - [Disabling jobs](#disabling-jobs)
+- [Running a job on a schedule](#running-a-job-on-a-schedule)
+  - [One run at a time per repository](#one-run-at-a-time-per-repository)
 - [Gating jobs with `run_only_if_changed`](#gating-jobs-with-run_only_if_changed)
 - [Throttling jobs with `cooldown_period`](#throttling-jobs-with-cooldown_period)
+- [Throttling a job when a superset lands with `cooldown_on`](#throttling-a-job-when-a-superset-lands-with-cooldown_on)
 - [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout)
 - [Generating jobs dynamically](#generating-jobs-dynamically)
 - [Requirements](#requirements)
+- [Appendix](#appendix)
+  - [jj revset aliases](#jj-revset-aliases)
+
+## Use cases
+
+- Keeping generated files (API clients, protobuf bindings, lock files) in
+  sync with their sources
+- Applying organization-wide refactors or policy changes across many
+  repositories
+- Automating any periodic code transformation that should go through a
+  review process
 
 ## Installation
 
@@ -98,7 +121,7 @@ needs a GitHub or GitLab API token in the environment. See
    ```
 
 4. **Run the job locally.** In the default `local` mode nothing is pushed
-   and no MR is created — repoactive just records the diff your script
+   and no MR is created - repoactive just records the diff your script
    produced on the branch `repoactive/uv-lock-upgrade` and prints a
    `jj op restore` command to undo the run:
 
@@ -109,7 +132,7 @@ needs a GitHub or GitLab API token in the environment. See
 5. **Publish it.** Put the API token your platform uses in the environment
    (`GITHUB_TOKEN` for GitHub.com, `GITLAB_TOKEN` for GitLab.com by
    default), fetch the latest base branch, then let repoactive push the
-   branch and open — or update — the merge request:
+   branch and open - or update - the merge request:
 
    ```bash
    jj git fetch          # repoactive never fetches on its own
@@ -147,7 +170,7 @@ need to write is the script that produces the change.
 3. If the script produced a diff, it records the change. With `--mode push`
    or `--mode publish`, it pushes the branch; with `--mode publish`, it also
    creates or updates the merge request. On a re-run, if the diff matches
-   what is already on the branch, the commit and branch are left untouched —
+   what is already on the branch, the commit and branch are left untouched -
    avoiding an unnecessary push that would re-trigger CI pipelines. The
    commit is updated (and the branch pushed) only when the diff itself
    changes or when `title`/`commit_title_prefix` changed. Command output
@@ -161,7 +184,7 @@ need to write is the script that produces the change.
 > **jj commits the whole working tree.** Because `repoactive` uses jj, every
 > new file your script creates inside the working directory is added to the
 > commit unless it is git-ignored. There is no way to select which
-> working-tree changes become part of the commit — they all will. Keep
+> working-tree changes become part of the commit - they all will. Keep
 > `.gitignore` up to date so build artifacts, caches, and other stray files
 > your script produces do not end up in the diff.
 
@@ -175,21 +198,12 @@ local clone advances past it.
 
 **Fetch before each run.** Run `jj git fetch` (or `git fetch --prune`) in
 the same cron job or CI pipeline that invokes `repoactive`, before it. If
-you do not, jobs rebase onto a stale base and — most importantly —
+you do not, jobs rebase onto a stale base and - most importantly -
 [`cooldown_period`](#throttling-jobs-with-cooldown_period) never engages,
 because the commit that would trigger it has not reached the local base
 branch. See
 [ADR 0005](docs/adr/0005-local-repository-is-the-source-of-truth.md).
 
-## Use cases
-
-- Keeping generated files (API clients, protobuf bindings, lock files) in
-  sync with their sources
-- Applying organization-wide refactors or policy changes across many
-  repositories
-- Automating any periodic code transformation that should go through a
-  review process
-
 ## Usage
 
 ```bash
@@ -323,28 +337,6 @@ repoactive recent-commits --status unmerged
 | `--status [all\|merged\|unmerged]` | `-s`  | Filter by merge status into trunk (default: `all`)     |
 | `--debug`                          | `-d`  | Enable debug logging                                   |
 
-### jj revset aliases
-
-To query repoactive commits directly in jj, add these aliases to your
-repository config (`jj config set --repo`) or your global config
-(`jj config set --user`):
-
-```toml
-[revset-aliases]
-'repoactive()' = 'description(regex:"(?m)^Repoactive-Job: ")'
-'repoactive_merged()' = 'repoactive() & ::trunk()'
-'repoactive_unmerged()' = 'repoactive() & ~(::trunk())'
-```
-
-Then use them directly in jj:
-
-```bash
-jj log -r 'repoactive()'
-jj log -r 'repoactive_unmerged()'
-jj log -r 'repoactive() & committer_date(after:"2025-01-01")'
-jj log -r 'repoactive() & description(regex:"(?m)^Repoactive-Job: uv-lock-upgrade$")'
-```
-
 ## Validating configuration
 
 ```
@@ -372,12 +364,8 @@ code 1.
 Validation checks include unknown keys, missing required fields, invalid
 `depends_on` references, and circular job dependencies.
 
-| Option             | Short | Description                                                                                                                  |
-| ------------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `--config PATH`    | `-c`  | Config file or directory of `*.toml` files; repeat to merge. Default: `.repoactive.d/` and `.repoactive.toml` under `--repo` |
-| `--set NAME=VALUE` | `-s`  | Override a config value (repeatable); `NAME` is a dotted TOML key, `VALUE` a TOML expression. Wins over `--config`           |
-| `--repo PATH`      | `-r`  | jj repository path (default: `.`)                                                                                            |
-| `--debug`          | `-d`  | Enable debug logging                                                                                                         |
+The command accepts the same `--config`, `--set`, `--repo`, and `--debug`
+options as [`repoactive run`](#usage).
 
 ## Listing jobs
 
@@ -403,12 +391,8 @@ build           Build the project   enabled
     └── deploy  Deploy to staging   nightly, risky
 ```
 
-| Option             | Short | Description                                                                                                                  |
-| ------------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `--config PATH`    | `-c`  | Config file or directory of `*.toml` files; repeat to merge. Default: `.repoactive.d/` and `.repoactive.toml` under `--repo` |
-| `--set NAME=VALUE` | `-s`  | Override a config value (repeatable); `NAME` is a dotted TOML key, `VALUE` a TOML expression. Wins over `--config`           |
-| `--repo PATH`      | `-r`  | jj repository path (default: `.`)                                                                                            |
-| `--debug`          | `-d`  | Enable debug logging                                                                                                         |
+The command accepts the same `--config`, `--set`, `--repo`, and `--debug`
+options as [`repoactive run`](#usage).
 
 ## Listing tags
 
@@ -417,7 +401,7 @@ repoactive info tags [OPTIONS]
 ```
 
 Group the configured jobs by tag and print each tag with the jobs carrying
-it. Jobs are grouped by their effective tags — the tags driving job
+it. Jobs are grouped by their effective tags - the tags driving job
 selection: a job's explicit `tags`, or the implicit `enabled`/`disabled` tag
 when it has none. Within each tag, jobs are shown as a dependency tree in
 topological order: a job is nested under its `depends_on` targets carrying
@@ -442,12 +426,8 @@ nightly:
   benchmark            Run nightly benchmarks  nightly
 ```
 
-| Option             | Short | Description                                                                                                                  |
-| ------------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `--config PATH`    | `-c`  | Config file or directory of `*.toml` files; repeat to merge. Default: `.repoactive.d/` and `.repoactive.toml` under `--repo` |
-| `--set NAME=VALUE` | `-s`  | Override a config value (repeatable); `NAME` is a dotted TOML key, `VALUE` a TOML expression. Wins over `--config`           |
-| `--repo PATH`      | `-r`  | jj repository path (default: `.`)                                                                                            |
-| `--debug`          | `-d`  | Enable debug logging                                                                                                         |
+The command accepts the same `--config`, `--set`, `--repo`, and `--debug`
+options as [`repoactive run`](#usage).
 
 ## Configuration
 
@@ -456,135 +436,200 @@ passed via `--config`). See [Config file locations](#config-file-locations)
 for how the defaults are discovered and how to split the config across
 several files.
 
+A minimal config with a single job:
+
+```toml
+[job.uv-lock-upgrade]
+command = "uv lock --upgrade"
+title = "build: upgrade dependencies"
+```
+
 Every key in `[job-defaults]` supplies the default for the matching per-job
 key; any job may override it by setting the same key in its `[job.<name>]`
 block.
 
+### `[job-defaults]`
+
+**MR/PR options:**
+
+- **`labels`** (default: `[]`) - Labels applied to every MR/PR. Per-job
+  `labels` are merged with, not replaced by, this list.
+- **`auto_merge`** (default: `false`) - When `true`, enable auto-merge on
+  every MR/PR so it merges automatically once its pipeline passes. On
+  GitHub, the repository must have "Allow auto-merge" enabled in its
+  settings.
+
+**Branch and commit options:**
+
+- **`branch_prefix`** (default: `"repoactive/"`) - Prefix prepended to the
+  job name to form the branch name.
+- **`mr_title_prefix`** (default: `"[repoactive] "`) - Prefix prepended to
+  every MR/PR title. Set to `""` to disable.
+- **`commit_title_prefix`** (default: `"[repoactive] "`) - Prefix prepended
+  to every commit title. Set to `""` to disable.
+- **`base_branch`** (default: repo default) - Target branch for all jobs
+  that do not set their own.
+
+**Run control:**
+
+- **`cooldown_period`** (default: none) - Minimum time between a landed
+  change and the next run for any job. Format: `<number><unit>` where unit
+  is `s`, `m`, `h`, `d`, or `w` (e.g. `"7d"`). See
+  [Throttling jobs with `cooldown_period`](#throttling-jobs-with-cooldown_period).
+- **`timeout`** (default: `"2m"`) - Maximum runtime for a job's command.
+  Same format as `cooldown_period`. See
+  [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout).
+
+### `[job.<name>]`
+
+The table key is the job's unique name; the branch is always
+`branch_prefix + name`. Job names may contain letters, digits, hyphens, and
+underscores.
+
+**Required:**
+
+- **`command`** - Shell command (or executable path) run in the repository
+  working directory. A non-zero exit is a failure.
+- **`title`** - MR/PR title (also the commit subject, after
+  `commit_title_prefix`).
+
+**MR/PR options:**
+
+- **`description`** - Body text of the MR/PR.
+- **`labels`** (default: `[]`) - Extra labels for this job's MR/PR, merged
+  with `job-defaults.labels`.
+- **`draft`** (default: `false`) - Open the MR/PR as a draft. On GitHub,
+  draft state cannot be changed after creation.
+- **`create_mr`** (default: `true`) - Whether to create an MR/PR: `true`
+  (always), `false` (push the branch but skip the MR), or
+  `"unless-superseded"` (skip when a dependent's MR from the same run
+  already contains this job's changes - see [Stacking MRs](#stacking-mrs)).
+- **`auto_merge`** (default: inherited from `job-defaults`) - When `true`,
+  enable auto-merge on this job's MR/PR.
+
+**Branch and commit options:**
+
+- **`base_branch`** (default: inherited) - Target branch for this job's
+  MR/PR.
+- **`branch_prefix`** (default: inherited) - Override the branch-name prefix
+  for this job only.
+- **`mr_title_prefix`** (default: inherited) - Override the MR/PR title
+  prefix for this job only.
+- **`commit_title_prefix`** (default: inherited) - Override the commit title
+  prefix for this job only.
+- **`output_in_commit`** (default: `true`) - Append the job's command and
+  its captured output to the commit message. Set to `false` to keep the
+  commit message clean.
+
+**Run control:**
+
+- **`disabled`** (default: `false`) - Exclude this job from the bare
+  `repoactive run`. Sugar for `tags = ["disabled"]`; mutually exclusive with
+  `tags`. See [Disabling jobs](#disabling-jobs).
+- **`tags`** (default: none) - Tags for job selection. A job with no tags
+  carries the implicit `enabled` tag and runs in the bare `repoactive run`;
+  setting any explicit tag removes `enabled`. See
+  [Selecting jobs with tags](#selecting-jobs-with-tags).
+- **`depends_on`** (default: `[]`) - Jobs whose output this job builds on.
+  See [Stacking MRs](#stacking-mrs).
+- **`run_only_if_changed`** (default: `[]`) - Only run this job if at least
+  one listed job produced a diff in the current run. See
+  [Gating jobs with `run_only_if_changed`](#gating-jobs-with-run_only_if_changed).
+- **`cooldown_period`** (default: inherited) - Minimum time between a landed
+  change and the next run. See
+  [Throttling jobs with `cooldown_period`](#throttling-jobs-with-cooldown_period).
+- **`cooldown_on`** (default: `[]`) - Broader jobs that subsume this one; a
+  recent landing of any of them also throttles this job. Requires a
+  `cooldown_period`. See
+  [Throttling a job when a superset lands with `cooldown_on`](#throttling-a-job-when-a-superset-lands-with-cooldown_on).
+- **`timeout`** (default: inherited) - Maximum runtime for this job's
+  command. Set to `"0s"` to disable the timeout entirely. See
+  [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout).
+- **`emits_jobs`** (default: `false`) - Generator job: the command writes
+  `*.toml` job fragments into `$REPOACTIVE_JOBS_DIR` instead of producing a
+  diff. See [Generating jobs dynamically](#generating-jobs-dynamically).
+
+### Stacking MRs
+
+When `depends_on` is set, `repoactive` starts the job's script from a
+working tree that already contains all listed dependencies' diffs, rather
+than from the plain base branch. The resulting MR branch includes both the
+dependency changes and the new job's changes on top, and links to the parent
+MRs are automatically added to the MR description.
+
+Because a dependent's MR already contains its dependencies' changes, a
+dependency chain normally opens one MR per job that produced a diff. Setting
+`create_mr = "unless-superseded"` on the earlier jobs collapses that: such a
+job skips its MR when a dependent job produced an MR in the same run, so the
+chain yields a single MR on the topmost job that actually changed something
+
+- falling back to the job below it when the jobs above came up empty. The
+  branch is still pushed either way. Only the current run counts: a
+  dependent that is empty, failed, on cooldown, or not selected does not
+  suppress anything. See
+  [ADR 0009](docs/adr/0009-unless-superseded-mr-creation.md) for details and
+  limitations.
+
+### Example
+
 ```toml
 [job-defaults]
-# Prefix prepended to job.name to form the branch name
-branch_prefix = "repoactive/"
-# Prefix prepended to every MR/PR title (set to "" to disable)
-mr_title_prefix = "[repoactive] "
-# Prefix prepended to every commit title (set to "" to disable)
-commit_title_prefix = "[repoactive] "
-# Labels applied to every MR/PR unless overridden per job
-labels = ["repoactive"]
-# Optional: default target branch for jobs that do not set their own
-# (default: repo default branch)
 base_branch = "main"
-# Optional: default cooldown_period applied to jobs that do not set their own
-# (default: none). See "Throttling jobs with cooldown_period" below.
+labels = ["repoactive"]
 cooldown_period = "7d"
-# Optional: default timeout applied to jobs that do not set their own
-# (default: "2m"). See "Limiting job runtime with timeout" below.
-timeout = "1h"
+auto_merge = true
+branch_prefix = "bot/"
+commit_title_prefix = "[bot] "
+timeout = "10m"
 
-# The table key is the job's unique name; the branch is always
-# <branch_prefix><name>.
 [job.regenerate-api-client]
-# Script run in the repo working directory; non-zero exit = failure
 command = "python scripts/regen_api.py"
-# MR/PR title
 title = "api: regenerate API client"
-# Optional: MR description
 description = "Automated regeneration of the API client from the OpenAPI spec."
-# Optional: extra labels (merged with job-defaults.labels)
-labels = ["automated", "api"]
-# Optional: target branch (default: repo default branch)
-base_branch = "main"
-# Optional: open the MR/PR as a draft (default: false)
-draft = false
-# Optional: create an MR/PR for this job (default: true). Set to false to
-# push the branch without opening an MR/PR, or to "unless-superseded" to skip
-# the MR/PR when a dependent job's MR from the same run already contains this
-# job's changes (see the notes on depends_on below).
-create_mr = true
-# Optional: append the job's command and its output to the commit message
-# (default: true). Set to false to keep the commit message clean.
-output_in_commit = true
-# Optional: skip this job on "run all" invocations (default: false). Sugar for
-# tags = ["disabled"]; mutually exclusive with tags. See "Disabling jobs" below.
-disabled = false
-# Optional: tags for job selection (default: none -> the job carries the
-# implicit "enabled" tag and runs in the bare `repoactive run`). Setting any tag
-# removes "enabled", so the job runs only via `repoactive run --tag <tag>`. See
-# "Selecting jobs with tags" below.
-# tags = ["nightly"]
-# Optional: override branch_prefix/mr_title_prefix/commit_title_prefix from
-# job-defaults for this job only.
+labels = ["api"]
 mr_title_prefix = "[api] "
-# Optional: only run this job if at least one of the named jobs produced a
-# diff in the current run. If none of them changed anything, this job is
-# skipped (with a no-op result so dependents still run). Names need not be
-# in depends_on; any job that ran before this one can be listed.
-# run_only_if_changed = ["other-job"]
-# Optional: minimum time between landed changes for this job. If a commit
-# from this job landed on the base branch within this window, the job is
-# skipped. Format: <number><unit>, unit one of s, m, h, d, w (e.g. "7d").
-cooldown_period = "7d"
-# Optional: maximum runtime for this job's command. When it expires the
-# command's process group is killed and the job fails. Same format as
-# cooldown_period.
-timeout = "30m"
+create_mr = "unless-superseded"
 
 [job.sync-license-headers]
 command = "./scripts/add_license_headers.sh"
 title = "sync license headers"
+draft = true
 
 [job.integration-tests-update]
 command = "./scripts/update_integration_tests.py"
 title = "tests: update integration tests"
-# Optional: run this job on top of the merged output of the listed jobs
 depends_on = ["regenerate-api-client", "sync-license-headers"]
+timeout = "30m"
 ```
 
+### `[platform.<name>]`
+
 For public GitHub.com or GitLab.com repositories no platform declaration is
-needed — `repoactive` detects the remote URL automatically. To use a
+needed - `repoactive` detects the remote URL automatically. To use a
 self-hosted instance, add a `[platform.<name>]` section (the name is a label
 of your choosing; platforms are matched to a repository by their `url`):
 
+- **`url`** - Base URL of the platform instance (e.g.
+  `"https://gitlab.example.com"`).
+- **`type`** - `"github"` or `"gitlab"`.
+- **`token_env`** - Name of the environment variable holding the API token.
+
 ```toml
 [platform.company-gitlab]
-# Base URL of the platform instance
 url = "https://gitlab.example.com"
-# Name of the env var holding the API token
 token_env = "GITLAB_TOKEN"
-# type must be either "github" or "gitlab"
 type = "gitlab"
 ```
 
-The branch for each job is always `branch_prefix + job.name`, where
-`branch_prefix` is the job's own value if set, otherwise
-`job-defaults.branch_prefix`. Secrets are kept out of the config file by
-referencing environment variable names rather than inline values.
-
-The token named by `token_env` is **stripped from the environment job
-commands run in**, so a script cannot read the credential `repoactive` uses
-to push and create MRs. A job that needs its own credential must be given a
-separate one. `repoactive` otherwise trusts job commands — they run
-arbitrary code against the working tree — so the trust boundary is the
-config that defines them; see
+Secrets are kept out of the config file by referencing environment variable
+names rather than inline values. The token named by `token_env` is
+**stripped from the environment job commands run in**, so a script cannot
+read the credential `repoactive` uses to push and create MRs. A job that
+needs its own credential must be given a separate one. `repoactive`
+otherwise trusts job commands - they run arbitrary code against the working
+tree - so the trust boundary is the config that defines them; see
 [ADR 0006](docs/adr/0006-job-commands-are-trusted.md).
 
-When `depends_on` is set, `repoactive` starts the job's script from a
-working tree that has all listed dependency branches merged together, rather
-than from the plain base branch. The resulting MR branch will therefore
-include both the dependency jobs and the new job on top. Links to the parent
-MRs are automatically added to the MR description.
-
-Because a dependent's MR already contains its dependencies' changes, a
-dependency chain normally opens one MR per job that produced a diff. Setting
-`create_mr = "unless-superseded"` on the earlier jobs collapses that: such a
-job skips its MR whenever a dependent job produced an MR in the same run, so
-the chain yields a single MR on the topmost job that actually changed
-something — falling back to the job below it when the jobs above came up
-empty. The branch is still pushed either way. Only the current run counts: a
-dependent that is empty, failed, on cooldown, or not selected does not
-suppress anything. See
-[ADR 0009](docs/adr/0009-unless-superseded-mr-creation.md) for details and
-limitations.
-
 ### Config file locations
 
 When no `--config`/`-c` option is given, `repoactive` looks for
@@ -609,8 +654,8 @@ directory, not `--repo`.
 
 `--set NAME=VALUE`/`-s` tweaks individual config values without editing a
 file. It is merged as the last, highest-priority source, so it wins over
-everything discovered or passed with `--config`. `NAME` is a TOML key —
-dotted keys reach into tables — and `VALUE` is a TOML expression, so strings
+everything discovered or passed with `--config`. `NAME` is a TOML key -
+dotted keys reach into tables - and `VALUE` is a TOML expression, so strings
 need quoting:
 
 ```bash
@@ -635,7 +680,7 @@ which then needs the full set of fields (`url`, `type`, `token_env`).
 `--set` is available on `run`, `validate-config`, `info jobs`, and
 `info tags`. Each `--set` is validated as its own source (like a separate
 config file), so it can amend existing jobs but cannot introduce a brand-new
-job across several flags — put a new job's required fields in one expression
+job across several flags - put a new job's required fields in one expression
 (e.g. `--set 'job.x = {command = "…", title = "…"}'`) or a config file. An
 unknown key or malformed value is reported with the offending `--set`
 argument named.
@@ -648,14 +693,14 @@ a set of tags, with a smart default:
 - a plain job (no `tags`, not `disabled`) carries the implicit `enabled`
   tag;
 - `disabled = true` is sugar for `tags = ["disabled"]`;
-- setting `tags = [...]` uses exactly those tags — and, importantly, **drops
+- setting `tags = [...]` uses exactly those tags - and, importantly, **drops
   the implicit `enabled` tag** unless you list it yourself.
 
 `repoactive run` with no arguments is shorthand for
 `repoactive run --tag enabled`: it runs every job carrying `enabled`. Pass
 `--tag`/`-t` (repeatable) to select a different set; a job runs if it
 carries **any** of the requested tags. Naming jobs and passing tags can be
-combined — the selection is the union of the two.
+combined - the selection is the union of the two.
 
 ```bash
 # Run all jobs tagged "weekly" (regardless of whether they also have "enabled")
@@ -666,7 +711,7 @@ repoactive run --tag nightly regenerate-api-client
 ```
 
 Requesting a tag that no job carries is an error, exactly like naming an
-unknown job — a typo in a crontab's `--tag` fails loudly instead of silently
+unknown job - a typo in a crontab's `--tag` fails loudly instead of silently
 running zero jobs. This also means a scheduled entry whose tag has lost its
 last member fails until you remove the entry (or re-tag a job); a tag only
 exists as a value on jobs, so an empty tag is indistinguishable from a
@@ -676,9 +721,9 @@ Because assigning a tag removes the implicit `enabled` tag, **tags are
 load-bearing, not free-form labels**: tagging a job takes it out of the bare
 `repoactive run`. If you want a job to stay in the default run _and_ belong
 to a group, list both: `tags = ["enabled", "weekly"]`. (For MR/PR labels,
-use `labels` — a separate concept.)
+use `labels` - a separate concept.)
 
-Tag selection is _explicit_ selection, so — like naming a job — it ignores
+Tag selection is _explicit_ selection, so - like naming a job - it ignores
 the `enabled`/`disabled` defaults and force-includes dependencies. The bare
 `repoactive run` is _implicit_ selection: a job whose dependency is not
 itself selected is dropped
@@ -696,7 +741,7 @@ latest `trunk()` and the command is re-run against it. (With
 `--mode push` it is just a branch.)
 
 This means a job's schedule tag governs when a _new_ branch is created,
-while the default run keeps an existing branch rebased and current — you
+while the default run keeps an existing branch rebased and current - you
 don't have to wait for the next weekly run to resolve a conflict with
 `trunk()`. Once the branch lands, its commit becomes an ancestor of
 `trunk()`, so the job drops back to its normal tag-driven cadence. (A
@@ -710,6 +755,13 @@ it out of normal runs; it is exactly sugar for `tags = ["disabled"]` (so the
 two are mutually exclusive). The flag only affects the bare
 `repoactive run`:
 
+```toml
+[job.experimental-refactor]
+command = "./scripts/refactor.sh"
+title = "chore: apply experimental refactor"
+disabled = true
+```
+
 - On `repoactive run`, disabled jobs are skipped, along with any job that
   `depends_on` one (its dependency would not be produced).
 - Naming a job explicitly overrides it: `repoactive run my-job` runs
@@ -717,13 +769,13 @@ two are mutually exclusive). The flag only affects the bare
   `repoactive run --tag disabled`, which runs everything currently turned
   off.
 
-### Running a job on a schedule
+## Running a job on a schedule
 
-`repoactive` is not a daemon and has no built-in scheduler — the cadence of
+`repoactive` is not a daemon and has no built-in scheduler - the cadence of
 a job is whatever cadence you invoke it with. To run a job on a fixed
 schedule, tag it and have an OS cron job select that tag. The tag keeps the
 job out of the bare `repoactive run`, and the crontab decides the membership
-in one place — add or remove `weekly` jobs by editing the config, not the
+in one place - add or remove `weekly` jobs by editing the config, not the
 crontab:
 
 ```toml
@@ -740,18 +792,18 @@ tags = ["weekly"]
 ```
 
 Because the cron is the sole trigger, the command runs exactly when cron
-fires — once, whether or not it produces a diff. This is more reliable than
+fires - once, whether or not it produces a diff. This is more reliable than
 inferring a schedule from `repoactive`'s own history: real cron is stateful
 and excludes the other days, whereas `repoactive` only ever sees what has
 _landed_ (see `cooldown_period` below).
 
-#### One run at a time per repository
+### One run at a time per repository
 
 A `repoactive run` takes an exclusive per-repository lock for its duration,
 so two runs against the same repository never interleave (and corrupt each
 other's branches and temporary workspaces). If a run is started while
-another is still in progress — a slow run overrunning the next cron tick,
-say — the second one **exits immediately with status code 2** instead of
+another is still in progress - a slow run overrunning the next cron tick,
+say - the second one **exits immediately with status code 2** instead of
 waiting or racing. That code is distinct from the generic failure code (1),
 so a wrapper can treat "already running" as benign:
 
@@ -786,7 +838,7 @@ tags = ["weekly"]
 Here `prek-run-all` is only useful when `prek-autoupdate` changed something:
 if `prek-autoupdate` found no hooks to update, running `prek-run-all` would
 produce an empty diff anyway. With `run_only_if_changed`, the skip is
-explicit and immediate — `prek-run-all` never even starts.
+explicit and immediate - `prek-run-all` never even starts.
 
 Key behaviour:
 
@@ -796,7 +848,7 @@ Key behaviour:
   skipped, it is treated as having produced no diff.
 - **Dependents are unaffected.** A skipped job records a no-op result (like
   a job on cooldown), so any job that `depends_on` it still runs on the base
-  branch — the skip does not cascade.
+  branch - the skip does not cascade.
 - **No ordering constraint.** Names in `run_only_if_changed` do not have to
   appear in `depends_on`. Any job that runs before this one in topological
   order can be listed; in practice most usages name a direct dependency, as
@@ -825,6 +877,44 @@ runs: `repoactive` does not fetch, so a clone that has not pulled the merge
 will not see the cooldown and will re-run the job. See
 [Keeping the local clone current](#keeping-the-local-clone-current).
 
+## Throttling a job when a superset lands with `cooldown_on`
+
+Some jobs are strict supersets of others. `uv lock --upgrade` refreshes
+every dependency group, so its diff already contains everything
+`uv lock --upgrade-group=dev` would produce. Re-running the narrower job
+right after the broad one landed just opens a redundant MR.
+
+Listing the broader jobs in `cooldown_on` widens the narrow job's cooldown
+check: it is throttled when **its own trailer or any listed job's trailer**
+last landed within its `cooldown_period`. So once the full upgrade lands,
+the group-scoped job stays quiet for the cooldown window instead of
+re-running.
+
+```toml
+[job.full-lock]
+command = "uv lock --upgrade"
+title = "chore: update all dependencies"
+cooldown_period = "7d"
+
+[job.dev-lock]
+command = "uv lock --upgrade-group=dev"
+title = "chore: update dev dependencies"
+cooldown_period = "7d"
+cooldown_on = ["full-lock"]
+```
+
+`cooldown_on` requires a `cooldown_period` on the same job (its own or one
+inherited from `[job-defaults]`); without a window there is nothing to
+throttle against, so a config that sets one without the other is rejected.
+The relationship is one-directional and needs no change to the broad job -
+it still writes only its own trailer.
+
+This only suppresses _starting_ a redundant run. A narrow job that already
+has an open, unmerged branch is always refreshed regardless of cooldown (see
+[Keeping unmerged branches current](#keeping-unmerged-branches-current)), so
+its branch is rebased and, if the change is now redundant, self-closes on
+the next run.
+
 ## Limiting job runtime with `timeout`
 
 A job's `command` can hang or run away. Setting `timeout` caps how long the
@@ -840,10 +930,25 @@ zero duration (`timeout = "0s"`) disables the timeout entirely; since TOML
 has no null value, this is how a job opts out of a timeout set in
 `job-defaults`.
 
+```toml
+[job-defaults]
+timeout = "10m"       # raise the built-in 2m default for all jobs
+
+[job.slow-codegen]
+command = "./scripts/slow_codegen.sh"
+title = "chore: regenerate bindings"
+timeout = "30m"       # this job needs extra time
+
+[job.quick-lint]
+command = "ruff check ."
+title = "chore: fix lint"
+timeout = "0s"        # opt out of the timeout entirely
+```
+
 ## Generating jobs dynamically
 
-Sometimes the useful set of jobs depends on the repository's contents — one
-job per package in a monorepo, one per entry in a manifest — and you don't
+Sometimes the useful set of jobs depends on the repository's contents - one
+job per package in a monorepo, one per entry in a manifest - and you don't
 want to hand-maintain them. A **generator** is an ordinary `[job.<name>]`
 with `emits_jobs = true`. Instead of producing a diff, its command writes
 one or more `*.toml` job fragments into the directory named by the
@@ -895,7 +1000,7 @@ Key points:
 > only re-run when the generator re-emits it, and the generator is gated by
 > the same landed commits (via the shared trailer). So overriding an emitted
 > job's `cooldown_period` only matters when you make it **longer** than the
-> generator's — then the job stays throttled even after the generator has
+> generator's - then the job stays throttled even after the generator has
 > run again. Making it **shorter** has no effect: while the generator is on
 > its own cooldown the job is never re-emitted, and by the time the
 > generator runs again the job's shorter window has long since elapsed
@@ -924,3 +1029,27 @@ design.
 - A GitLab or GitHub API token exposed via the environment variable named in
   `platform.token_env` (default: `GITHUB_TOKEN` for GitHub.com,
   `GITLAB_TOKEN` for GitLab.com)
+
+## Appendix
+
+### jj revset aliases
+
+To query repoactive commits directly in jj, add these aliases to your
+repository config (`jj config set --repo`) or your global config
+(`jj config set --user`):
+
+```toml
+[revset-aliases]
+'repoactive()' = 'description(regex:"(?m)^Repoactive-Job: ")'
+'repoactive_merged()' = 'repoactive() & ::trunk()'
+'repoactive_unmerged()' = 'repoactive() & ~(::trunk())'
+```
+
+Then use them directly in jj:
+
+```bash
+jj log -r 'repoactive()'
+jj log -r 'repoactive_unmerged()'
+jj log -r 'repoactive() & committer_date(after:"2025-01-01")'
+jj log -r 'repoactive() & description(regex:"(?m)^Repoactive-Job: uv-lock-upgrade$")'
+```