continuous-refactoring 0.3.0__tar.gz → 1.0.1__tar.gz

{continuous_refactoring-0.3.0 → continuous_refactoring-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: continuous-refactoring
-Version: 0.3.0
+Version: 1.0.1
 Summary: Continuous refactoring loop for AI coding agents
 Project-URL: Repository, https://github.com/bigH/continuous-refactoring
 Project-URL: Issues, https://github.com/bigH/continuous-refactoring/issues
@@ -69,6 +69,10 @@ uv pip install -e .
 
 That gives you the `continuous-refactoring` command.
 
+The CLI itself can be installed without `uv`, but the default validation command
+is `uv run pytest`. Pass `--validation-command pytest` or a project-specific
+script when the target repo does not use `uv`.
+
 Maintainers: see the [release checklist](https://github.com/bigH/continuous-refactoring/blob/main/docs/release.md).
 
 ## Fastest way to get one refactor
@@ -124,8 +128,8 @@ continuous-refactoring init --in-repo-taste
 
 # 2. (Optional) Write your refactoring taste — either edit the file, have an agent interview you,
 #    or refine an existing draft collaboratively
-continuous-refactoring taste --interview --with codex --model gpt-5 --effort high
-continuous-refactoring taste --refine --with codex --model gpt-5 --effort high
+continuous-refactoring taste --interview --with codex --model gpt-5
+continuous-refactoring taste --refine --with codex --model gpt-5
 
 # 3. Do one pass
 continuous-refactoring run-once \
@@ -141,22 +145,23 @@ continuous-refactoring run \
   --sleep 5
 ```
 
+Active taste agent modes require `--with` and `--model`; taste agent sessions
+always run at fixed `medium` effort.
+
 ## Subcommands
 
 | Command | What it does |
 |---|---|
 | `init` | Registers this directory as a project, creates a default `taste.md`, and can store `--live-migrations-dir` or `--in-repo-taste`. |
-| `taste` | Prints the active taste file path. Add `--interview` to have an agent author it, `--refine` to iteratively improve an existing taste doc, `--upgrade` to refresh stale taste dimensions, `--global` for the shared file, and `--force` to let `--interview` overwrite custom content after writing a `.bak`. |
+| `taste` | Prints the active taste file path. Add `--interview` to have an agent author it, `--refine` to iteratively improve an existing taste doc, `--upgrade` to refresh stale taste dimensions, `--global` for the shared file, and `--force` to let `--interview` overwrite custom content after writing a `.bak`. Active agent modes require `--with` and `--model`, then run at fixed `medium` effort. |
 | `run-once` | Single pass on one resolved target. No retry. If there is a diff and validation passes, it commits locally and prints the diffstat. |
 | `run` | The loop. Iterates refactor actions, retries on failure, and commits successful changes locally. Add `--focus-on-live-migrations` to bypass targeting and work only on eligible live migrations. |
 | `upgrade` | Checks that the global config manifest is current, rewrites it idempotently, and warns if the global taste file is stale. |
-| `migration list` | Lists visible migrations. Add `--status <status>` or `--awaiting-review` to filter. |
+| `migration list` | Lists visible migrations as TSV with headers. Add `--status <status>` or `--awaiting-review` to filter, or `--no-headers` for parsing. |
 | `migration doctor <slug-or-path>` | Validates one visible migration's consistency. |
 | `migration doctor --all` | Validates every visible migration plus internal transaction state. |
-| `migration review <slug-or-path>` | Starts staged review for a migration awaiting human review. Requires `--with`, `--model`, and `--effort`. |
-| `migration refine <slug-or-path>` | Records feedback for a planning or unexecuted ready migration and runs one staged planning revision. Requires `--message <text>` or `--file <path>`, plus `--with`, `--model`, and `--effort`; add `--show-agent-logs` to mirror the planning agent. |
-
-Legacy `review list` and `review perform <migration>` remain compatibility aliases; prefer `migration list --awaiting-review` and `migration review`.
+| `migration review <slug-or-path>` | Starts staged review for a migration awaiting human review. Requires `--with` and `--model`; review runs at fixed internal `high` effort. |
+| `migration refine <slug-or-path>` | Records feedback for a planning or unexecuted ready migration and runs one staged planning revision. Requires `--message <text>` or `--file <path>`, plus `--with` and `--model`; refine runs at fixed internal `high` effort. Add `--show-agent-logs` to mirror the planning agent. |
 
 ## Targeting / Useful flags
 
@@ -174,8 +179,9 @@ These flags are not mutually exclusive, but only the highest-priority populated
 - `--scope-instruction "clean up the auth module"` — extra free-text scoping. If selected file patterns resolve nothing, this becomes the useful fallback context.
 
 If `--globs` or `--extensions` match no tracked files and there is no
-`--scope-instruction`, `run` completes successfully with zero refactor actions.
-`--paths` is literal input and is not filtered through `git ls-files`.
+`--scope-instruction`, `run` completes successfully with zero refactor actions;
+`run-once` falls back to a no-file `general refactoring` target. `--paths` is
+literal input and is not filtered through `git ls-files`.
 
 If you provide none of `--targets`, `--globs`, `--extensions`, or `--paths`,
 then `run` and `run-once` require `--scope-instruction`; the driver still
@@ -186,12 +192,13 @@ scope text as context for that target.
 
 - `init --live-migrations-dir PATH` — enables the larger-refactoring workflow for this project. The path is stored repo-relative in the project registry and created if missing.
 - `init --in-repo-taste [PATH]` — stores this project's taste file in the repo and remembers the repo-relative path. Defaults to `.continuous-refactoring/taste.md`; re-run `init --in-repo-taste ...` to choose a different path.
-- `migration list` — shows visible migrations; `--awaiting-review` narrows to human-review handoffs.
+- `migration list` — shows visible migrations as TSV with headers; `--awaiting-review` narrows to human-review handoffs and `--no-headers` keeps parser-friendly rows only.
 - `migration doctor <slug-or-path>` / `migration doctor --all` — read-only consistency checks. Doctor reports problems; it does not repair them.
-- `migration review <slug-or-path> --with ... --model ... --effort ...` — resolves an `awaiting_human_review` migration through a staged workspace.
-- `migration refine <slug-or-path> (--message <text>|--file <path>) --with ... --model ... --effort ... [--show-agent-logs]` — adds user feedback to a planning or unexecuted ready migration and resumes planning through the `revise` step when reopening ready work.
-- `taste --refine` — opens a collaborative editing session for the taste file. The agent keeps refining until you tell it to write, then the session ends automatically after the settled write.
-- `taste --upgrade` — re-interviews for taste dimensions added since your last version. No-op when already current; use `taste --refine` if you want to rework the doc anyway.
+- `migration review <slug-or-path> --with ... --model ...` — resolves an `awaiting_human_review` migration through a staged workspace at fixed internal `high` effort.
+- `migration refine <slug-or-path> (--message <text>|--file <path>) --with ... --model ... [--show-agent-logs]` — adds user feedback to a planning or unexecuted ready migration and resumes planning through the `revise` step when reopening ready work at fixed internal `high` effort.
+- `taste --refine --with ... --model ...` — opens a collaborative editing session for the taste file. The agent keeps refining until you tell it to write, then the session ends automatically after the settled write.
+- `taste --upgrade --with ... --model ...` — re-interviews for taste dimensions added since your last version. No-op when already current; use `taste --refine` if you want to rework the doc anyway.
+- Taste agent sessions always use fixed `medium` effort.
 - `taste --force` — only applies to `--interview`; it allows a customized taste file to be overwritten after backing it up to `taste.md.bak`.
 
 Canonical migration commands:
@@ -200,11 +207,12 @@ Canonical migration commands:
 continuous-refactoring migration list
 continuous-refactoring migration list --status planning
 continuous-refactoring migration list --awaiting-review
+continuous-refactoring migration list --no-headers
 continuous-refactoring migration doctor <slug-or-path>
 continuous-refactoring migration doctor --all
-continuous-refactoring migration review <slug-or-path> --with codex --model gpt-5 --effort high
-continuous-refactoring migration refine <slug-or-path> --message "split the risky phase" --with codex --model gpt-5 --effort high
-continuous-refactoring migration refine <slug-or-path> --file feedback.md --with codex --model gpt-5 --effort high
+continuous-refactoring migration review <slug-or-path> --with codex --model gpt-5
+continuous-refactoring migration refine <slug-or-path> --message "split the risky phase" --with codex --model gpt-5
+continuous-refactoring migration refine <slug-or-path> --file feedback.md --with codex --model gpt-5
 ```
 
 ### Shared `run` / `run-once` flags
@@ -213,7 +221,7 @@ continuous-refactoring migration refine <slug-or-path> --file feedback.md --with
 - `--default-effort` — default effort for run calls. Defaults to `low`. Valid labels are `low`, `medium`, `high`, `xhigh`.
 - `--max-allowed-effort` — cap for target overrides and migration escalation. Defaults to `xhigh`.
 - `--repo-root PATH` — repository root; defaults to the current directory.
-- `--validation-command` — defaults to `uv run pytest`. Swap it for whatever keeps your repo honest.
+- `--validation-command` — defaults to `uv run pytest`. This is parsed with `shlex.split` and run without a shell, so simple commands like `pytest -q` work, but shell syntax such as `cmd && cmd`, pipes, redirects, or leading `VAR=value` assignments is not interpreted. Put compound validation in a script.
 - `--timeout` — per-agent-call timeout in seconds.
 - `--show-agent-logs` / `--show-command-logs` — mirror output to your terminal instead of just logging.
 - `--refactoring-prompt` — override the default refactoring prompt.
@@ -242,9 +250,9 @@ continuous-refactoring migration refine <slug-or-path> --file feedback.md --with
 Each run writes to `$TMPDIR/continuous-refactoring/<run-id>/`:
 
 - `summary.json` — rolling status, counts, per-attempt stats
-- `events.jsonl` — structured event log with call roles such as `classify`,
-  `planning.<step>`, `phase.ready-check`, `phase.execute`, and
-  `phase.validation`
+- `events.jsonl` — structured event log with call roles such as
+  `scope-expansion`, `classify`, `planning.<step>`, `planning.publish`,
+  `phase.ready-check`, `phase.execute`, and `phase.validation`
 - `run.log` — human-readable log
 - `attempt-NNN/[retry-NN/]refactor/` — per-attempt agent + test stdout/stderr
 - `baseline/initial/` — baseline validation stdout/stderr before work starts
@@ -271,7 +279,7 @@ The taste file is a short bullet list of your refactoring preferences. It gets i
 - Project taste: `~/.local/share/continuous-refactoring/projects/<uuid>/taste.md`, or the repo-local path chosen with `init --in-repo-taste [PATH]`
 - Global taste: `~/.local/share/continuous-refactoring/global/taste.md`
 
-Project taste wins over global. Use `taste` to print the active path, `taste --interview` to bootstrap one, `taste --refine` to rework it with an agent, or edit the file directly any time.
+Project taste wins over global. Use `taste` to print the active path, `taste --interview --with ... --model ...` to bootstrap one, `taste --refine --with ... --model ...` to rework it with an agent, or edit the file directly any time.
 
 ## Larger refactorings
 
@@ -346,7 +354,7 @@ Before executing a phase, a ready-check agent verifies that the current phase pr
 
 - **ready: yes** — phase executes; on green tests, the phase is marked done, any prior deferral markers are cleared, and the migration advances immediately to the next phase.
 - **ready: no** — manifest activity is bumped, a retry cooldown is started, and a future `wake_up_on` is recorded when needed; the tick moves on.
-- **ready: unverifiable** — the migration is flagged `awaiting_human_review` and put on cooldown. Automated migration ticks skip flagged migrations until review clears the flag. Use `migration list --awaiting-review` to find it and `migration review <slug-or-path> --with ... --model ... --effort ...` to resolve it interactively.
+- **ready: unverifiable** — the migration is marked `awaiting_human_review` and put on cooldown. Automated migration ticks skip migrations awaiting human review until review clears the flag. Use `migration list --awaiting-review` to find it and `migration review <slug-or-path> --with ... --model ...` to resolve it interactively.
 
 Human-facing migration references use the relative phase spec path, for example `phase-2-failure-report.md`. The manifest cursor stores the phase `name`, not a numeric index.
 

{continuous_refactoring-0.3.0 → continuous_refactoring-1.0.1}/README.md

@@ -46,6 +46,10 @@ uv pip install -e .
 
 That gives you the `continuous-refactoring` command.
 
+The CLI itself can be installed without `uv`, but the default validation command
+is `uv run pytest`. Pass `--validation-command pytest` or a project-specific
+script when the target repo does not use `uv`.
+
 Maintainers: see the [release checklist](https://github.com/bigH/continuous-refactoring/blob/main/docs/release.md).
 
 ## Fastest way to get one refactor
@@ -101,8 +105,8 @@ continuous-refactoring init --in-repo-taste
 
 # 2. (Optional) Write your refactoring taste — either edit the file, have an agent interview you,
 #    or refine an existing draft collaboratively
-continuous-refactoring taste --interview --with codex --model gpt-5 --effort high
-continuous-refactoring taste --refine --with codex --model gpt-5 --effort high
+continuous-refactoring taste --interview --with codex --model gpt-5
+continuous-refactoring taste --refine --with codex --model gpt-5
 
 # 3. Do one pass
 continuous-refactoring run-once \
@@ -118,22 +122,23 @@ continuous-refactoring run \
   --sleep 5
 ```
 
+Active taste agent modes require `--with` and `--model`; taste agent sessions
+always run at fixed `medium` effort.
+
 ## Subcommands
 
 | Command | What it does |
 |---|---|
 | `init` | Registers this directory as a project, creates a default `taste.md`, and can store `--live-migrations-dir` or `--in-repo-taste`. |
-| `taste` | Prints the active taste file path. Add `--interview` to have an agent author it, `--refine` to iteratively improve an existing taste doc, `--upgrade` to refresh stale taste dimensions, `--global` for the shared file, and `--force` to let `--interview` overwrite custom content after writing a `.bak`. |
+| `taste` | Prints the active taste file path. Add `--interview` to have an agent author it, `--refine` to iteratively improve an existing taste doc, `--upgrade` to refresh stale taste dimensions, `--global` for the shared file, and `--force` to let `--interview` overwrite custom content after writing a `.bak`. Active agent modes require `--with` and `--model`, then run at fixed `medium` effort. |
 | `run-once` | Single pass on one resolved target. No retry. If there is a diff and validation passes, it commits locally and prints the diffstat. |
 | `run` | The loop. Iterates refactor actions, retries on failure, and commits successful changes locally. Add `--focus-on-live-migrations` to bypass targeting and work only on eligible live migrations. |
 | `upgrade` | Checks that the global config manifest is current, rewrites it idempotently, and warns if the global taste file is stale. |
-| `migration list` | Lists visible migrations. Add `--status <status>` or `--awaiting-review` to filter. |
+| `migration list` | Lists visible migrations as TSV with headers. Add `--status <status>` or `--awaiting-review` to filter, or `--no-headers` for parsing. |
 | `migration doctor <slug-or-path>` | Validates one visible migration's consistency. |
 | `migration doctor --all` | Validates every visible migration plus internal transaction state. |
-| `migration review <slug-or-path>` | Starts staged review for a migration awaiting human review. Requires `--with`, `--model`, and `--effort`. |
-| `migration refine <slug-or-path>` | Records feedback for a planning or unexecuted ready migration and runs one staged planning revision. Requires `--message <text>` or `--file <path>`, plus `--with`, `--model`, and `--effort`; add `--show-agent-logs` to mirror the planning agent. |
-
-Legacy `review list` and `review perform <migration>` remain compatibility aliases; prefer `migration list --awaiting-review` and `migration review`.
+| `migration review <slug-or-path>` | Starts staged review for a migration awaiting human review. Requires `--with` and `--model`; review runs at fixed internal `high` effort. |
+| `migration refine <slug-or-path>` | Records feedback for a planning or unexecuted ready migration and runs one staged planning revision. Requires `--message <text>` or `--file <path>`, plus `--with` and `--model`; refine runs at fixed internal `high` effort. Add `--show-agent-logs` to mirror the planning agent. |
 
 ## Targeting / Useful flags
 
@@ -151,8 +156,9 @@ These flags are not mutually exclusive, but only the highest-priority populated
 - `--scope-instruction "clean up the auth module"` — extra free-text scoping. If selected file patterns resolve nothing, this becomes the useful fallback context.
 
 If `--globs` or `--extensions` match no tracked files and there is no
-`--scope-instruction`, `run` completes successfully with zero refactor actions.
-`--paths` is literal input and is not filtered through `git ls-files`.
+`--scope-instruction`, `run` completes successfully with zero refactor actions;
+`run-once` falls back to a no-file `general refactoring` target. `--paths` is
+literal input and is not filtered through `git ls-files`.
 
 If you provide none of `--targets`, `--globs`, `--extensions`, or `--paths`,
 then `run` and `run-once` require `--scope-instruction`; the driver still
@@ -163,12 +169,13 @@ scope text as context for that target.
 
 - `init --live-migrations-dir PATH` — enables the larger-refactoring workflow for this project. The path is stored repo-relative in the project registry and created if missing.
 - `init --in-repo-taste [PATH]` — stores this project's taste file in the repo and remembers the repo-relative path. Defaults to `.continuous-refactoring/taste.md`; re-run `init --in-repo-taste ...` to choose a different path.
-- `migration list` — shows visible migrations; `--awaiting-review` narrows to human-review handoffs.
+- `migration list` — shows visible migrations as TSV with headers; `--awaiting-review` narrows to human-review handoffs and `--no-headers` keeps parser-friendly rows only.
 - `migration doctor <slug-or-path>` / `migration doctor --all` — read-only consistency checks. Doctor reports problems; it does not repair them.
-- `migration review <slug-or-path> --with ... --model ... --effort ...` — resolves an `awaiting_human_review` migration through a staged workspace.
-- `migration refine <slug-or-path> (--message <text>|--file <path>) --with ... --model ... --effort ... [--show-agent-logs]` — adds user feedback to a planning or unexecuted ready migration and resumes planning through the `revise` step when reopening ready work.
-- `taste --refine` — opens a collaborative editing session for the taste file. The agent keeps refining until you tell it to write, then the session ends automatically after the settled write.
-- `taste --upgrade` — re-interviews for taste dimensions added since your last version. No-op when already current; use `taste --refine` if you want to rework the doc anyway.
+- `migration review <slug-or-path> --with ... --model ...` — resolves an `awaiting_human_review` migration through a staged workspace at fixed internal `high` effort.
+- `migration refine <slug-or-path> (--message <text>|--file <path>) --with ... --model ... [--show-agent-logs]` — adds user feedback to a planning or unexecuted ready migration and resumes planning through the `revise` step when reopening ready work at fixed internal `high` effort.
+- `taste --refine --with ... --model ...` — opens a collaborative editing session for the taste file. The agent keeps refining until you tell it to write, then the session ends automatically after the settled write.
+- `taste --upgrade --with ... --model ...` — re-interviews for taste dimensions added since your last version. No-op when already current; use `taste --refine` if you want to rework the doc anyway.
+- Taste agent sessions always use fixed `medium` effort.
 - `taste --force` — only applies to `--interview`; it allows a customized taste file to be overwritten after backing it up to `taste.md.bak`.
 
 Canonical migration commands:
@@ -177,11 +184,12 @@ Canonical migration commands:
 continuous-refactoring migration list
 continuous-refactoring migration list --status planning
 continuous-refactoring migration list --awaiting-review
+continuous-refactoring migration list --no-headers
 continuous-refactoring migration doctor <slug-or-path>
 continuous-refactoring migration doctor --all
-continuous-refactoring migration review <slug-or-path> --with codex --model gpt-5 --effort high
-continuous-refactoring migration refine <slug-or-path> --message "split the risky phase" --with codex --model gpt-5 --effort high
-continuous-refactoring migration refine <slug-or-path> --file feedback.md --with codex --model gpt-5 --effort high
+continuous-refactoring migration review <slug-or-path> --with codex --model gpt-5
+continuous-refactoring migration refine <slug-or-path> --message "split the risky phase" --with codex --model gpt-5
+continuous-refactoring migration refine <slug-or-path> --file feedback.md --with codex --model gpt-5
 ```
 
 ### Shared `run` / `run-once` flags
@@ -190,7 +198,7 @@ continuous-refactoring migration refine <slug-or-path> --file feedback.md --with
 - `--default-effort` — default effort for run calls. Defaults to `low`. Valid labels are `low`, `medium`, `high`, `xhigh`.
 - `--max-allowed-effort` — cap for target overrides and migration escalation. Defaults to `xhigh`.
 - `--repo-root PATH` — repository root; defaults to the current directory.
-- `--validation-command` — defaults to `uv run pytest`. Swap it for whatever keeps your repo honest.
+- `--validation-command` — defaults to `uv run pytest`. This is parsed with `shlex.split` and run without a shell, so simple commands like `pytest -q` work, but shell syntax such as `cmd && cmd`, pipes, redirects, or leading `VAR=value` assignments is not interpreted. Put compound validation in a script.
 - `--timeout` — per-agent-call timeout in seconds.
 - `--show-agent-logs` / `--show-command-logs` — mirror output to your terminal instead of just logging.
 - `--refactoring-prompt` — override the default refactoring prompt.
@@ -219,9 +227,9 @@ continuous-refactoring migration refine <slug-or-path> --file feedback.md --with
 Each run writes to `$TMPDIR/continuous-refactoring/<run-id>/`:
 
 - `summary.json` — rolling status, counts, per-attempt stats
-- `events.jsonl` — structured event log with call roles such as `classify`,
-  `planning.<step>`, `phase.ready-check`, `phase.execute`, and
-  `phase.validation`
+- `events.jsonl` — structured event log with call roles such as
+  `scope-expansion`, `classify`, `planning.<step>`, `planning.publish`,
+  `phase.ready-check`, `phase.execute`, and `phase.validation`
 - `run.log` — human-readable log
 - `attempt-NNN/[retry-NN/]refactor/` — per-attempt agent + test stdout/stderr
 - `baseline/initial/` — baseline validation stdout/stderr before work starts
@@ -248,7 +256,7 @@ The taste file is a short bullet list of your refactoring preferences. It gets i
 - Project taste: `~/.local/share/continuous-refactoring/projects/<uuid>/taste.md`, or the repo-local path chosen with `init --in-repo-taste [PATH]`
 - Global taste: `~/.local/share/continuous-refactoring/global/taste.md`
 
-Project taste wins over global. Use `taste` to print the active path, `taste --interview` to bootstrap one, `taste --refine` to rework it with an agent, or edit the file directly any time.
+Project taste wins over global. Use `taste` to print the active path, `taste --interview --with ... --model ...` to bootstrap one, `taste --refine --with ... --model ...` to rework it with an agent, or edit the file directly any time.
 
 ## Larger refactorings
 
@@ -323,7 +331,7 @@ Before executing a phase, a ready-check agent verifies that the current phase pr
 
 - **ready: yes** — phase executes; on green tests, the phase is marked done, any prior deferral markers are cleared, and the migration advances immediately to the next phase.
 - **ready: no** — manifest activity is bumped, a retry cooldown is started, and a future `wake_up_on` is recorded when needed; the tick moves on.
-- **ready: unverifiable** — the migration is flagged `awaiting_human_review` and put on cooldown. Automated migration ticks skip flagged migrations until review clears the flag. Use `migration list --awaiting-review` to find it and `migration review <slug-or-path> --with ... --model ... --effort ...` to resolve it interactively.
+- **ready: unverifiable** — the migration is marked `awaiting_human_review` and put on cooldown. Automated migration ticks skip migrations awaiting human review until review clears the flag. Use `migration list --awaiting-review` to find it and `migration review <slug-or-path> --with ... --model ...` to resolve it interactively.
 
 Human-facing migration references use the relative phase spec path, for example `phase-2-failure-report.md`. The manifest cursor stores the phase `name`, not a numeric index.
 

{continuous_refactoring-0.3.0 → continuous_refactoring-1.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "continuous-refactoring"
-version = "0.3.0"
+version = "1.0.1"
 description = "Continuous refactoring loop for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.10"

{continuous_refactoring-0.3.0 → continuous_refactoring-1.0.1}/src/continuous_refactoring/cli.py

@@ -32,7 +32,6 @@ from continuous_refactoring.loop import (
 )
 from continuous_refactoring.migration_cli import handle_migration
 from continuous_refactoring.migrations import MIGRATION_STATUSES
-from continuous_refactoring.review_cli import handle_review
 
 _PACKAGE_DISTRIBUTION = "continuous-refactoring"
 _TASTE_WARNING = "warning: taste out of date — run `continuous-refactoring taste --upgrade`"
@@ -40,6 +39,7 @@ _GLOBAL_TASTE_WARNING = (
     "warning: global taste is out of date — "
     "run 'continuous-refactoring taste --upgrade' to update."
 )
+_TASTE_AGENT_EFFORT = "medium"
 
 
 def _version_banner() -> str:
@@ -155,6 +155,10 @@ def _add_taste_parser(subparsers: argparse._SubParsersAction) -> None:
     taste_parser = subparsers.add_parser(
         "taste",
         help="Manage refactoring taste files.",
+        description=(
+            "Manage project or global taste files. Agent-backed modes require "
+            "--with and --model."
+        ),
     )
     taste_parser.set_defaults(handler=_handle_taste)
     taste_parser.add_argument(
@@ -191,11 +195,6 @@ def _add_taste_parser(subparsers: argparse._SubParsersAction) -> None:
         default=None,
         help="Model name for --interview, --upgrade, or --refine.",
     )
-    taste_parser.add_argument(
-        "--effort",
-        default=None,
-        help="Effort level for --interview, --upgrade, or --refine.",
-    )
     taste_parser.add_argument(
         "--force",
         action="store_true",
@@ -206,7 +205,8 @@ def _add_taste_parser(subparsers: argparse._SubParsersAction) -> None:
 def _add_run_once_parser(subparsers: argparse._SubParsersAction) -> None:
     run_once_parser = subparsers.add_parser(
         "run-once",
-        help="Single refactoring attempt (one agent call, no fix retry).",
+        help="Run one routed refactoring action without fix retry.",
+        description="Run one routed refactoring action without fix retry.",
     )
     run_once_parser.set_defaults(handler=_handle_run_once)
     _add_common_args(run_once_parser)
@@ -215,7 +215,8 @@ def _add_run_once_parser(subparsers: argparse._SubParsersAction) -> None:
 def _add_run_parser(subparsers: argparse._SubParsersAction) -> None:
     run_parser = subparsers.add_parser(
         "run",
-        help="Continuous refactoring loop with fix-prompt retry.",
+        help="Run routed refactoring actions with fix-prompt retry.",
+        description="Run routed refactoring actions with fix-prompt retry.",
     )
     run_parser.set_defaults(handler=_handle_run)
     _add_common_args(run_parser)
@@ -229,13 +230,14 @@ def _add_run_parser(subparsers: argparse._SubParsersAction) -> None:
         "--max-refactors",
         type=int,
         default=None,
-        help="Refactor actions to run.",
+        help="Actions to run.",
     )
     run_parser.add_argument(
         "--focus-on-live-migrations",
         action="store_true",
         help=(
-            "Iterate only on live migrations until every one is done or blocked. "
+            "Iterate only on eligible live migrations until done, deferred, "
+            "blocked, or failure budget trips. "
             "Bypasses targeting and --max-refactors requirements."
         ),
     )
@@ -258,31 +260,11 @@ def _add_run_parser(subparsers: argparse._SubParsersAction) -> None:
     )
 
 
-def _add_review_parser(subparsers: argparse._SubParsersAction) -> None:
-    review_parser = subparsers.add_parser(
-        "review",
-        help="Review migrations awaiting human review.",
-    )
-    review_parser.set_defaults(handler=handle_review)
-    review_sub = review_parser.add_subparsers(dest="review_command")
-    review_sub.add_parser("list", help="List migrations flagged for review.")
-    perform_parser = review_sub.add_parser(
-        "perform",
-        help="Perform review on a flagged migration.",
-    )
-    perform_parser.add_argument("migration", help="Migration name to review.")
-    perform_parser.add_argument(
-        "--with", dest="agent", choices=("codex", "claude"), required=True,
-        help="Agent backend.",
-    )
-    perform_parser.add_argument("--model", required=True, help="Model name.")
-    perform_parser.add_argument("--effort", required=True, help="Effort level.")
-
-
 def _add_migration_parser(subparsers: argparse._SubParsersAction) -> None:
     migration_parser = subparsers.add_parser(
         "migration",
-        help="Inspect live migrations.",
+        help="Inspect and manage live migrations.",
+        description="Inspect and manage live migrations.",
     )
     migration_parser.set_defaults(handler=handle_migration)
     migration_sub = migration_parser.add_subparsers(dest="migration_command")
@@ -302,6 +284,11 @@ def _add_migration_parser(subparsers: argparse._SubParsersAction) -> None:
         action="store_true",
         help="Only show migrations awaiting human review.",
     )
+    list_parser.add_argument(
+        "--no-headers",
+        action="store_true",
+        help="Omit the TSV header row.",
+    )
 
     doctor_parser = migration_sub.add_parser(
         "doctor",
@@ -320,7 +307,11 @@ def _add_migration_parser(subparsers: argparse._SubParsersAction) -> None:
 
     review_parser = migration_sub.add_parser(
         "review",
-        help="Perform staged review on a flagged migration.",
+        help="Resolve a migration awaiting human review in a staged workspace.",
+        description=(
+            "Resolve a migration awaiting human review in a staged workspace. "
+            "Requires --with and --model."
+        ),
     )
     review_parser.add_argument("target", help="Migration slug or contained path.")
     review_parser.add_argument(
@@ -328,13 +319,11 @@ def _add_migration_parser(subparsers: argparse._SubParsersAction) -> None:
         help="Agent backend.",
     )
     review_parser.add_argument("--model", required=True, help="Model name.")
-    review_parser.add_argument(
-        "--effort", choices=EFFORT_TIERS, required=True, help="Effort level."
-    )
 
     refine_parser = migration_sub.add_parser(
         "refine",
-        help="Refine a planning migration with user feedback.",
+        help="Apply feedback to a planning or unexecuted ready migration.",
+        description="Apply feedback to a planning or unexecuted ready migration.",
     )
     refine_parser.add_argument("target", help="Migration slug or contained path.")
     feedback_group = refine_parser.add_mutually_exclusive_group(required=True)
@@ -349,9 +338,6 @@ def _add_migration_parser(subparsers: argparse._SubParsersAction) -> None:
         help="Agent backend.",
     )
     refine_parser.add_argument("--model", required=True, help="Model name.")
-    refine_parser.add_argument(
-        "--effort", choices=EFFORT_TIERS, required=True, help="Effort level."
-    )
     refine_parser.add_argument(
         "--show-agent-logs",
         action="store_true",
@@ -380,7 +366,6 @@ def build_parser() -> argparse.ArgumentParser:
     )
     upgrade_parser.set_defaults(handler=_handle_upgrade)
     _add_migration_parser(subparsers)
-    _add_review_parser(subparsers)
 
     return parser
 
@@ -499,7 +484,9 @@ def _configure_repo_taste(
     if not current.exists():
         ensure_taste_file(destination)
         return
-    if current.resolve() == destination.resolve():
+    current_resolved = current.resolve()
+    destination_resolved = destination.resolve()
+    if current_resolved == destination_resolved:
         return
     if not current.is_file():
         raise ContinuousRefactorError(
@@ -529,15 +516,17 @@ def _configure_live_migrations_dir(
     if current is None or not current.exists():
         destination.mkdir(parents=True, exist_ok=True)
         return
+    current_resolved = current.resolve()
+    destination_resolved = destination.resolve()
     if not current.is_dir():
         raise ContinuousRefactorError(
             f"Configured live migrations path is not a directory: {current}"
         )
-    if current.resolve() == destination.resolve():
+    if current_resolved == destination_resolved:
         return
     if (
-        destination.resolve().is_relative_to(current.resolve())
-        or current.resolve().is_relative_to(destination.resolve())
+        destination_resolved.is_relative_to(current_resolved)
+        or current_resolved.is_relative_to(destination_resolved)
     ):
         raise ContinuousRefactorError(
             "Live migrations directory cannot be moved into itself or one of "
@@ -620,9 +609,7 @@ def _active_taste_mode(args: argparse.Namespace) -> str | None:
 
 
 def _taste_agent_flags_set(args: argparse.Namespace) -> bool:
-    return any(
-        getattr(args, name, None) is not None for name in ("agent", "model", "effort")
-    )
+    return any(getattr(args, name, None) is not None for name in ("agent", "model"))
 
 
 def _require_taste_action_flags(
@@ -630,14 +617,12 @@ def _require_taste_action_flags(
     action: str,
     agent: str | None,
     model: str | None,
-    effort: str | None,
 ) -> None:
     missing = [
         flag
         for flag, value in (
             ("--with", agent),
             ("--model", model),
-            ("--effort", effort),
         )
         if not value
     ]
@@ -661,7 +646,7 @@ def _run_taste_agent(
         returncode = run_agent_interactive_until_settled(
             args.agent,
             args.model,
-            args.effort,
+            _TASTE_AGENT_EFFORT,
             prompt,
             Path.cwd().resolve(),
             content_path=path,
@@ -729,7 +714,7 @@ def _handle_taste(args: argparse.Namespace) -> None:
     if mode is None:
         if _taste_agent_flags_set(args):
             print(
-                "Error: --with/--model/--effort require --interview, --upgrade, or --refine.",
+                "Error: --with/--model require --interview, --upgrade, or --refine.",
                 file=sys.stderr,
             )
             raise SystemExit(2)
@@ -741,7 +726,6 @@ def _handle_taste(args: argparse.Namespace) -> None:
         action=mode,
         agent=getattr(args, "agent", None),
         model=getattr(args, "model", None),
-        effort=getattr(args, "effort", None),
     )
     return _TASTE_MODE_HANDLERS[mode](args)