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

{continuous_refactoring-0.2.0 → continuous_refactoring-0.3.0}/.gitignore

@@ -1,4 +1,6 @@
 .scratchpad/
+tmpdir/
+.pytest_cache/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: continuous-refactoring
-Version: 0.2.0
+Version: 0.3.0
 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
@@ -32,6 +32,8 @@ Small, test-gated cleanup commits by an AI coding agent.
 
 Think of it as a supervised janitor loop: the agent proposes a cleanup, your tests decide if it stays.
 
+Here's [an article](https://artisincode.com/essays/how-i-use-unspent-tokens/) I wrote about it.
+
 ## Install
 
 Try it without installing:
@@ -92,15 +94,18 @@ continuous-refactoring run \
   --max-attempts 2
 ```
 
-That keeps sweeping targets until it runs out, hits your caps, or starts failing.
+That runs up to 10 refactor actions, then stops sooner if the finite target file
+runs out or the loop starts failing. Use `run --focus-on-live-migrations` when
+you want the loop to work only on eligible live migrations; it bypasses target
+selection and `--max-refactors`.
 
 ## What it does
 
-- Resolves a target from `--targets`, `--globs`, `--extensions`, or `--paths`, with optional natural-language scoping via `--scope-instruction`.
+- Resolves each source action from `--targets`, `--globs`, `--extensions`, or `--paths`, with optional natural-language scoping via `--scope-instruction`.
 - Runs the agent with a refactoring prompt + your "taste" guidelines.
 - Runs your validation command (default: `uv run pytest`).
 - If green and there's a diff, it commits locally and leaves the branch for you to inspect.
-- Repeats until it runs out of targets, hits the retry budget, or stacks too many failures.
+- Repeats until it spends the action budget, exhausts a finite target file, hits the retry budget, or stacks too many failures.
 
 ## Requirements
 
@@ -143,10 +148,15 @@ continuous-refactoring run \
 | `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`. |
 | `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 targets, retries on failure, and commits successful targets locally. |
+| `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. |
-| `review list` | Lists migrations flagged for human review (`awaiting_human_review`). |
-| `review perform <migration>` | Starts an interactive agent session to resolve a flagged migration's review. Requires `--with`, `--model`, and `--effort`. |
+| `migration list` | Lists visible migrations. Add `--status <status>` or `--awaiting-review` to filter. |
+| `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`.
 
 ## Targeting / Useful flags
 
@@ -157,22 +167,46 @@ Target resolution is first-match-wins:
 
 These flags are not mutually exclusive, but only the highest-priority populated source is used.
 
-- `--targets path/to/targets.jsonl` — explicit list; one JSON object per line with `description`, `files`, optional `scoping`, `model-override`, `effort-override`. Effort overrides use `low`, `medium`, `high`, or `xhigh`.
-- `--globs 'src/**/*.py:tests/**/*.py'` — colon-separated globs; each matched file becomes its own target.
-- `--extensions .py,.ts` — shorthand that expands to `**/*.py`, `**/*.ts`; each matched file becomes its own target.
-- `--paths a.py:b.py` — literal paths, all treated as one target.
-- `--scope-instruction "clean up the auth module"` — extra free-text scoping. If file-based targeting resolves nothing, this becomes the useful fallback context.
+- `--targets path/to/targets.jsonl` — explicit finite list; one JSON object per line with `description`, `files`, optional `scoping`, `model-override`, `effort-override`. Effort overrides use `low`, `medium`, `high`, or `xhigh`. If `--max-refactors` is omitted, `run` processes the file once and stops.
+- `--globs 'src/**/*.py:tests/**/*.py'` — colon-separated globs matched once against tracked files from `git ls-files`; each refactor action samples one matched file, so files can repeat.
+- `--extensions .py,.ts` — shorthand that expands to `**/*.py`, `**/*.ts` against tracked files from `git ls-files`; each refactor action samples one matched file, so files can repeat.
+- `--paths a.py:b.py` — literal user-provided paths, all treated as one grouped target; each refactor action reuses that group.
+- `--scope-instruction "clean up the auth module"` — extra free-text scoping. If selected file patterns resolve nothing, this becomes the useful fallback context.
 
-If you provide none of `--targets`, `--globs`, `--extensions`, or `--paths`, then `run` and `run-once` require `--scope-instruction`.
+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`.
+
+If you provide none of `--targets`, `--globs`, `--extensions`, or `--paths`,
+then `run` and `run-once` require `--scope-instruction`; the driver still
+random-samples tracked files from `git ls-files` for each action and uses the
+scope text as context for that target.
 
 ### Migrations & taste flags
 
 - `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 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.
 - `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:
+
+```bash
+continuous-refactoring migration list
+continuous-refactoring migration list --status planning
+continuous-refactoring migration list --awaiting-review
+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
+```
+
 ### Shared `run` / `run-once` flags
 
 - `--with`, `--model` — required agent backend/model selection.
@@ -187,10 +221,11 @@ If you provide none of `--targets`, `--globs`, `--extensions`, or `--paths`, the
 
 ### `run`-only flags
 
-- `--max-attempts N` — per-target retry budget. `1` = no retry, `0` = unlimited (which means permanently broken targets will never give up).
-- `--max-refactors N` — cap the number of targets per run. Required unless you use `--targets`.
-- `--max-consecutive-failures N` — bail after N targets fail in a row. Default 3.
-- `--sleep SECONDS` — pause between completed targets. Useful when you want a long batch without hammering the repo or your agent budget.
+- `--max-attempts N` — per-action retry budget. `1` = no retry, `0` = unlimited (which means permanently broken actions will never give up).
+- `--max-refactors N` — cap the number of refactor actions per run. Required unless you use `--targets` or `--focus-on-live-migrations`.
+- `--focus-on-live-migrations` — bypass target selection and `--max-refactors`; iterate eligible live migrations until they are done, deferred, blocked, or the failure budget trips.
+- `--max-consecutive-failures N` — bail after N actions fail in a row. Default 3.
+- `--sleep SECONDS` — pause between completed actions. Useful when you want a long batch without hammering the repo or your agent budget.
 - `--commit-message-prefix TEXT` — subject prefix for successful refactor or migration-plan commits. Default `continuous refactor`.
 
 ## Safety behaviors
@@ -207,13 +242,27 @@ If you provide none of `--targets`, `--globs`, `--extensions`, or `--paths`, the
 Each run writes to `$TMPDIR/continuous-refactoring/<run-id>/`:
 
 - `summary.json` — rolling status, counts, per-attempt stats
-- `events.jsonl` — structured event log
+- `events.jsonl` — structured event log with call roles such as `classify`,
+  `planning.<step>`, `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
+- `classify/` — classifier agent stdout/stderr
+- `scope-expansion/` — scope candidates, selection, and bypass reason
+- `attempt-NNN/[retry-NN/]planning/<step>/` — planning agent stdout/stderr for
+  migration planning steps
+- `phase-ready-check/` — phase precondition agent stdout/stderr
+- `attempt-NNN/[retry-NN/]phase-execute/` — phase agent and validation logs
+- `migration-probes/action-NNN/` — migration probe logs during normal `run`
+  actions, including planning, phase ready-checks, and phase execution
 
 Mixed-effort runs are auditable: summaries and call events record the default effort, max allowed effort, requested effort, effective effort, source, and whether the request was capped.
 
-The path prints at startup. Grep it when something goes sideways.
+The path prints at startup. Grep it when something goes sideways. Failed
+non-commit decisions also write durable XDG snapshots under the project failure
+directory, usually
+`~/.local/share/continuous-refactoring/projects/<uuid>/failures/`.
 
 ## Taste files
 
@@ -241,7 +290,7 @@ This tells the CLI where to store migration artifacts. The path is repo-relative
 Each `run` / `run-once` tick now checks for eligible migration work before falling back to single-commit cleanups:
 
 1. **Classify** — a classifier agent reads the target and decides: `cohesive-cleanup` (one-shot path) or `needs-plan` (migration path).
-2. **Plan** — for `needs-plan` targets, a six-stage planning workflow runs: generate approaches → pick best → expand into phases → review → revise → final review. Artifacts land under `<live-migrations-dir>/<migration-name>/`.
+2. **Plan** — for `needs-plan` targets, each automation action runs exactly one planning step: approaches, pick-best, expand, review, optional revise/review-2, then final-review. Accepted steps update `.planning/state.json`, store stdout under `.planning/stages/`, and publish through a staged transaction. Failed current-step output stays in run artifacts and is not resume input.
 3. **Execute** — each phase is a self-contained unit of work. The tick picks the oldest eligible migration, checks whether its current phase precondition is satisfied, and executes it on the current branch. Phase completion is judged against the phase file's `## Definition of Done`; commit message identifies the migration as `migration/<name>/<phase-file>.md`.
 
 ### Migration directory layout
@@ -250,14 +299,20 @@ Each `run` / `run-once` tick now checks for eligible migration work before falli
 <live-migrations-dir>/
   <migration-name>/
     manifest.json          # status, phases, wake-up schedule
+    .planning/
+      state.json           # durable planning cursor and accepted step refs
+      stages/              # accepted planning stdout, suffixed on repeats
     plan.md                # the expanded plan
     approaches/            # candidate approaches considered during planning
     phase-1-<name>.md      # per-phase specification
     phase-2-<name>.md
     ...
+  __transactions__/        # internal staged publish state
   __intentional_skips__/   # migrations rejected at final review
 ```
 
+Do not edit `.planning/` or `__transactions__/` by hand. Use `migration doctor` when the shape looks wrong.
+
 ### Wake-up rules
 
 Migrations don't run on every tick. The scheduler now separates **activity** from
@@ -291,7 +346,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 `review list` to find it and `review perform <migration> --with ... --model ... --effort ...` to resolve it interactively.
+- **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.
 
 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.2.0 → continuous_refactoring-0.3.0}/README.md

@@ -9,6 +9,8 @@ Small, test-gated cleanup commits by an AI coding agent.
 
 Think of it as a supervised janitor loop: the agent proposes a cleanup, your tests decide if it stays.
 
+Here's [an article](https://artisincode.com/essays/how-i-use-unspent-tokens/) I wrote about it.
+
 ## Install
 
 Try it without installing:
@@ -69,15 +71,18 @@ continuous-refactoring run \
   --max-attempts 2
 ```
 
-That keeps sweeping targets until it runs out, hits your caps, or starts failing.
+That runs up to 10 refactor actions, then stops sooner if the finite target file
+runs out or the loop starts failing. Use `run --focus-on-live-migrations` when
+you want the loop to work only on eligible live migrations; it bypasses target
+selection and `--max-refactors`.
 
 ## What it does
 
-- Resolves a target from `--targets`, `--globs`, `--extensions`, or `--paths`, with optional natural-language scoping via `--scope-instruction`.
+- Resolves each source action from `--targets`, `--globs`, `--extensions`, or `--paths`, with optional natural-language scoping via `--scope-instruction`.
 - Runs the agent with a refactoring prompt + your "taste" guidelines.
 - Runs your validation command (default: `uv run pytest`).
 - If green and there's a diff, it commits locally and leaves the branch for you to inspect.
-- Repeats until it runs out of targets, hits the retry budget, or stacks too many failures.
+- Repeats until it spends the action budget, exhausts a finite target file, hits the retry budget, or stacks too many failures.
 
 ## Requirements
 
@@ -120,10 +125,15 @@ continuous-refactoring run \
 | `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`. |
 | `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 targets, retries on failure, and commits successful targets locally. |
+| `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. |
-| `review list` | Lists migrations flagged for human review (`awaiting_human_review`). |
-| `review perform <migration>` | Starts an interactive agent session to resolve a flagged migration's review. Requires `--with`, `--model`, and `--effort`. |
+| `migration list` | Lists visible migrations. Add `--status <status>` or `--awaiting-review` to filter. |
+| `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`.
 
 ## Targeting / Useful flags
 
@@ -134,22 +144,46 @@ Target resolution is first-match-wins:
 
 These flags are not mutually exclusive, but only the highest-priority populated source is used.
 
-- `--targets path/to/targets.jsonl` — explicit list; one JSON object per line with `description`, `files`, optional `scoping`, `model-override`, `effort-override`. Effort overrides use `low`, `medium`, `high`, or `xhigh`.
-- `--globs 'src/**/*.py:tests/**/*.py'` — colon-separated globs; each matched file becomes its own target.
-- `--extensions .py,.ts` — shorthand that expands to `**/*.py`, `**/*.ts`; each matched file becomes its own target.
-- `--paths a.py:b.py` — literal paths, all treated as one target.
-- `--scope-instruction "clean up the auth module"` — extra free-text scoping. If file-based targeting resolves nothing, this becomes the useful fallback context.
+- `--targets path/to/targets.jsonl` — explicit finite list; one JSON object per line with `description`, `files`, optional `scoping`, `model-override`, `effort-override`. Effort overrides use `low`, `medium`, `high`, or `xhigh`. If `--max-refactors` is omitted, `run` processes the file once and stops.
+- `--globs 'src/**/*.py:tests/**/*.py'` — colon-separated globs matched once against tracked files from `git ls-files`; each refactor action samples one matched file, so files can repeat.
+- `--extensions .py,.ts` — shorthand that expands to `**/*.py`, `**/*.ts` against tracked files from `git ls-files`; each refactor action samples one matched file, so files can repeat.
+- `--paths a.py:b.py` — literal user-provided paths, all treated as one grouped target; each refactor action reuses that group.
+- `--scope-instruction "clean up the auth module"` — extra free-text scoping. If selected file patterns resolve nothing, this becomes the useful fallback context.
 
-If you provide none of `--targets`, `--globs`, `--extensions`, or `--paths`, then `run` and `run-once` require `--scope-instruction`.
+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`.
+
+If you provide none of `--targets`, `--globs`, `--extensions`, or `--paths`,
+then `run` and `run-once` require `--scope-instruction`; the driver still
+random-samples tracked files from `git ls-files` for each action and uses the
+scope text as context for that target.
 
 ### Migrations & taste flags
 
 - `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 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.
 - `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:
+
+```bash
+continuous-refactoring migration list
+continuous-refactoring migration list --status planning
+continuous-refactoring migration list --awaiting-review
+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
+```
+
 ### Shared `run` / `run-once` flags
 
 - `--with`, `--model` — required agent backend/model selection.
@@ -164,10 +198,11 @@ If you provide none of `--targets`, `--globs`, `--extensions`, or `--paths`, the
 
 ### `run`-only flags
 
-- `--max-attempts N` — per-target retry budget. `1` = no retry, `0` = unlimited (which means permanently broken targets will never give up).
-- `--max-refactors N` — cap the number of targets per run. Required unless you use `--targets`.
-- `--max-consecutive-failures N` — bail after N targets fail in a row. Default 3.
-- `--sleep SECONDS` — pause between completed targets. Useful when you want a long batch without hammering the repo or your agent budget.
+- `--max-attempts N` — per-action retry budget. `1` = no retry, `0` = unlimited (which means permanently broken actions will never give up).
+- `--max-refactors N` — cap the number of refactor actions per run. Required unless you use `--targets` or `--focus-on-live-migrations`.
+- `--focus-on-live-migrations` — bypass target selection and `--max-refactors`; iterate eligible live migrations until they are done, deferred, blocked, or the failure budget trips.
+- `--max-consecutive-failures N` — bail after N actions fail in a row. Default 3.
+- `--sleep SECONDS` — pause between completed actions. Useful when you want a long batch without hammering the repo or your agent budget.
 - `--commit-message-prefix TEXT` — subject prefix for successful refactor or migration-plan commits. Default `continuous refactor`.
 
 ## Safety behaviors
@@ -184,13 +219,27 @@ If you provide none of `--targets`, `--globs`, `--extensions`, or `--paths`, the
 Each run writes to `$TMPDIR/continuous-refactoring/<run-id>/`:
 
 - `summary.json` — rolling status, counts, per-attempt stats
-- `events.jsonl` — structured event log
+- `events.jsonl` — structured event log with call roles such as `classify`,
+  `planning.<step>`, `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
+- `classify/` — classifier agent stdout/stderr
+- `scope-expansion/` — scope candidates, selection, and bypass reason
+- `attempt-NNN/[retry-NN/]planning/<step>/` — planning agent stdout/stderr for
+  migration planning steps
+- `phase-ready-check/` — phase precondition agent stdout/stderr
+- `attempt-NNN/[retry-NN/]phase-execute/` — phase agent and validation logs
+- `migration-probes/action-NNN/` — migration probe logs during normal `run`
+  actions, including planning, phase ready-checks, and phase execution
 
 Mixed-effort runs are auditable: summaries and call events record the default effort, max allowed effort, requested effort, effective effort, source, and whether the request was capped.
 
-The path prints at startup. Grep it when something goes sideways.
+The path prints at startup. Grep it when something goes sideways. Failed
+non-commit decisions also write durable XDG snapshots under the project failure
+directory, usually
+`~/.local/share/continuous-refactoring/projects/<uuid>/failures/`.
 
 ## Taste files
 
@@ -218,7 +267,7 @@ This tells the CLI where to store migration artifacts. The path is repo-relative
 Each `run` / `run-once` tick now checks for eligible migration work before falling back to single-commit cleanups:
 
 1. **Classify** — a classifier agent reads the target and decides: `cohesive-cleanup` (one-shot path) or `needs-plan` (migration path).
-2. **Plan** — for `needs-plan` targets, a six-stage planning workflow runs: generate approaches → pick best → expand into phases → review → revise → final review. Artifacts land under `<live-migrations-dir>/<migration-name>/`.
+2. **Plan** — for `needs-plan` targets, each automation action runs exactly one planning step: approaches, pick-best, expand, review, optional revise/review-2, then final-review. Accepted steps update `.planning/state.json`, store stdout under `.planning/stages/`, and publish through a staged transaction. Failed current-step output stays in run artifacts and is not resume input.
 3. **Execute** — each phase is a self-contained unit of work. The tick picks the oldest eligible migration, checks whether its current phase precondition is satisfied, and executes it on the current branch. Phase completion is judged against the phase file's `## Definition of Done`; commit message identifies the migration as `migration/<name>/<phase-file>.md`.
 
 ### Migration directory layout
@@ -227,14 +276,20 @@ Each `run` / `run-once` tick now checks for eligible migration work before falli
 <live-migrations-dir>/
   <migration-name>/
     manifest.json          # status, phases, wake-up schedule
+    .planning/
+      state.json           # durable planning cursor and accepted step refs
+      stages/              # accepted planning stdout, suffixed on repeats
     plan.md                # the expanded plan
     approaches/            # candidate approaches considered during planning
     phase-1-<name>.md      # per-phase specification
     phase-2-<name>.md
     ...
+  __transactions__/        # internal staged publish state
   __intentional_skips__/   # migrations rejected at final review
 ```
 
+Do not edit `.planning/` or `__transactions__/` by hand. Use `migration doctor` when the shape looks wrong.
+
 ### Wake-up rules
 
 Migrations don't run on every tick. The scheduler now separates **activity** from
@@ -268,7 +323,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 `review list` to find it and `review perform <migration> --with ... --model ... --effort ...` to resolve it interactively.
+- **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.
 
 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.2.0 → continuous_refactoring-0.3.0}/pyproject.toml

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

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

@@ -5,7 +5,9 @@ import shutil
 import sys
 import uuid
 from collections.abc import Callable
+from importlib.metadata import version as metadata_version
 from pathlib import Path
+from typing import Literal
 
 __all__ = [
     "build_parser",
@@ -28,8 +30,11 @@ from continuous_refactoring.loop import (
     run_migrations_focused_loop,
     run_once,
 )
+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`"
 _GLOBAL_TASTE_WARNING = (
     "warning: global taste is out of date — "
@@ -37,6 +42,10 @@ _GLOBAL_TASTE_WARNING = (
 )
 
 
+def _version_banner() -> str:
+    return f"{_PACKAGE_DISTRIBUTION} {metadata_version(_PACKAGE_DISTRIBUTION)}"
+
+
 def parse_max_attempts(value: str) -> int:
     try:
         attempts = int(value)
@@ -220,7 +229,7 @@ def _add_run_parser(subparsers: argparse._SubParsersAction) -> None:
         "--max-refactors",
         type=int,
         default=None,
-        help="Distinct targets to process.",
+        help="Refactor actions to run.",
     )
     run_parser.add_argument(
         "--focus-on-live-migrations",
@@ -245,7 +254,7 @@ def _add_run_parser(subparsers: argparse._SubParsersAction) -> None:
         "--sleep",
         type=parse_sleep_seconds,
         default=0.0,
-        help="Seconds to sleep between completed targets.",
+        help="Seconds to sleep between completed actions.",
     )
 
 
@@ -270,10 +279,95 @@ def _add_review_parser(subparsers: argparse._SubParsersAction) -> None:
     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.",
+    )
+    migration_parser.set_defaults(handler=handle_migration)
+    migration_sub = migration_parser.add_subparsers(dest="migration_command")
+
+    list_parser = migration_sub.add_parser(
+        "list",
+        help="List visible migrations.",
+    )
+    list_parser.add_argument(
+        "--status",
+        choices=MIGRATION_STATUSES,
+        default=None,
+        help="Only show migrations with this status.",
+    )
+    list_parser.add_argument(
+        "--awaiting-review",
+        action="store_true",
+        help="Only show migrations awaiting human review.",
+    )
+
+    doctor_parser = migration_sub.add_parser(
+        "doctor",
+        help="Validate migration consistency.",
+    )
+    doctor_parser.add_argument(
+        "target",
+        nargs="?",
+        help="Migration slug or contained path.",
+    )
+    doctor_parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Validate every visible migration and transaction state.",
+    )
+
+    review_parser = migration_sub.add_parser(
+        "review",
+        help="Perform staged review on a flagged migration.",
+    )
+    review_parser.add_argument("target", help="Migration slug or contained path.")
+    review_parser.add_argument(
+        "--with", dest="agent", choices=("codex", "claude"), required=True,
+        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.",
+    )
+    refine_parser.add_argument("target", help="Migration slug or contained path.")
+    feedback_group = refine_parser.add_mutually_exclusive_group(required=True)
+    feedback_group.add_argument("--message", help="Refinement feedback text.")
+    feedback_group.add_argument(
+        "--file",
+        type=Path,
+        help="Path to a UTF-8 file containing refinement feedback.",
+    )
+    refine_parser.add_argument(
+        "--with", dest="agent", choices=("codex", "claude"), required=True,
+        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",
+        help="Mirror planning agent output to terminal.",
+    )
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         description="Continuous refactoring CLI for AI coding agents.",
     )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=_version_banner(),
+    )
     subparsers = parser.add_subparsers(dest="command")
 
     _add_init_parser(subparsers)
@@ -285,6 +379,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Verify and upgrade global configuration.",
     )
     upgrade_parser.set_defaults(handler=_handle_upgrade)
+    _add_migration_parser(subparsers)
     _add_review_parser(subparsers)
 
     return parser
@@ -312,36 +407,20 @@ def _handle_init(args: argparse.Namespace) -> None:
 
     try:
         if in_repo_taste_arg is not None:
-            repo_taste_resolved = (path / in_repo_taste_arg).resolve()
-            if not repo_taste_resolved.is_relative_to(path):
-                print(
-                    f"Error: --in-repo-taste must be inside the repo: {in_repo_taste_arg}",
-                    file=sys.stderr,
-                )
-                raise SystemExit(2)
-            if repo_taste_resolved.exists() and not repo_taste_resolved.is_file():
-                print(
-                    f"Error: --in-repo-taste must point to a file: {in_repo_taste_arg}",
-                    file=sys.stderr,
-                )
-                raise SystemExit(2)
-            repo_taste_relative = str(repo_taste_resolved.relative_to(path))
+            repo_taste_resolved, repo_taste_relative = _resolve_repo_relative_arg(
+                repo_root=path,
+                value=in_repo_taste_arg,
+                flag="--in-repo-taste",
+                expected_kind="file",
+            )
 
         if live_dir_arg is not None:
-            resolved_live = (path / live_dir_arg).resolve()
-            if not resolved_live.is_relative_to(path):
-                print(
-                    f"Error: --live-migrations-dir must be inside the repo: {live_dir_arg}",
-                    file=sys.stderr,
-                )
-                raise SystemExit(2)
-            if resolved_live.exists() and not resolved_live.is_dir():
-                print(
-                    f"Error: --live-migrations-dir must point to a directory: {live_dir_arg}",
-                    file=sys.stderr,
-                )
-                raise SystemExit(2)
-            live_dir_relative = str(resolved_live.relative_to(path))
+            resolved_live, live_dir_relative = _resolve_repo_relative_arg(
+                repo_root=path,
+                value=live_dir_arg,
+                flag="--live-migrations-dir",
+                expected_kind="directory",
+            )
 
         project = register_project(path)
         if repo_taste_relative is not None:
@@ -380,6 +459,36 @@ def _handle_init(args: argparse.Namespace) -> None:
         print(f"Live migrations dir: {resolved_live}")
 
 
+def _resolve_repo_relative_arg(
+    *,
+    repo_root: Path,
+    value: Path,
+    flag: str,
+    expected_kind: Literal["file", "directory"],
+) -> tuple[Path, str]:
+    resolved = (repo_root / value).resolve()
+    if not resolved.is_relative_to(repo_root):
+        print(
+            f"Error: {flag} must be inside the repo: {value}",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    if resolved.exists():
+        if expected_kind == "file" and not resolved.is_file():
+            print(
+                f"Error: {flag} must point to a file: {value}",
+                file=sys.stderr,
+            )
+            raise SystemExit(2)
+        if expected_kind == "directory" and not resolved.is_dir():
+            print(
+                f"Error: {flag} must point to a directory: {value}",
+                file=sys.stderr,
+            )
+            raise SystemExit(2)
+    return resolved, str(resolved.relative_to(repo_root))
+
+
 def _configure_repo_taste(
     *,
     current: Path,