Orchestrata Ultimate › Plans › briefs › rename-verb-integration

Packet: integrate the rename engine as a codetools dispatcher verb (no external script)

Source: plans/briefs/rename-verb-integration.md at 8a2cb42ad · last changed 2026-10-20 · first committed 2026-10-20 · 94 lines.

Prose pending.

Plan text

Packet: integrate the rename engine as a codetools dispatcher verb (no external script)

Status: DISPATCH-READY · Repo: /home/mohamed/workspace/orchestrata.codetools (branch master) Authority: Mohamed ruling 2026-10-20, verbatim: "rename must be integrated into codetools inside the module not an external script" (session 272, §5.5a). Follows ADR-0117 (the engine moved to codetools; this ruling sets its exposure seam) and ADR-0120's environment-resolution discipline.

Context (measured at HEAD, do not re-litigate)

• The rename engine lives INSIDE the package at src/codetools/refactor/rename/cli.py — but is exposed as the standalone console script rename_engine (pyproject.toml [project.scripts]). The ruling removes that exposure: the surface is the codetools dispatcher.
• The dispatcher discovers verbs mechanically: codetools.verbs.registry.discover_registrars() imports codetools.<activity>.cli.register for every PACKAGE with a cli.py (see src/codetools/verbs/registry.py and src/codetools/deploy/cli.py::register as the pattern). refactor/ is a package but has NO cli.py, so the rename engine is currently NOT a verb — that is the integration gap.
• src/codetools/refactor/rename/cli.py already has build_parser() with subcommands (symbol, module, plan, report …) and main(); its prog= still reads the dead rename_engine.py (the known defect).
• Measured references to rename_engine: pyproject.toml:31, cli.py (prog=), and tests/refactor/rename/test_rename_engine_cli.py (3 subprocess sites at .venv/bin/rename_engine + docstring), test_rename_engine_coverage.py and test_executor.py (docstring refs). The deployed /opt/codetools/bin/ holds NO rename_engine wrapper (measured) — nothing to re-point there.
• The §5.3 staleness guard is LIVE in this repo: after any src/ edit, every test run refuses until uv sync --dev --no-editable — re-sync BEFORE running lanes, or the guard (correctly) blocks you.

Deliverables

D1 — the verb (src)

• New src/codetools/refactor/cli.py with def register(sub) -> None that adds a rename subparser and attaches the rename engine's subcommands under it — the exact shape of deploy/cli.py::register.
• Refactor src/codetools/refactor/rename/cli.py so its subcommands attach to a passed-in parent subparser (e.g. def register(sub) there, used by both the new refactor/cli.py and the module's own build_parser()), keeping ONE definition of the argument surface — never duplicate the parser.
• Fix prog= to "codetools rename" (drop the dead rename_engine.py string entirely).
• Keep the module's main() (python -m codetools.refactor.rename … stays legal — the ruling bans the EXTERNAL SCRIPT, not module invocation).
• Acceptance: codetools --help lists rename; codetools rename --help lists the subcommands; collect_verbs() (or codetools.verbs.registry.build_parser()) walks rename <leaf> verbs; ruff + black clean on the touched files.

D2 — remove the console script

• Delete the rename_engine line from pyproject.toml [project.scripts]. uv.lock must NOT change (a script line is not a dependency) — verify git diff --stat uv.lock is empty before reporting.
• Acceptance: after uv sync --dev --no-editable, .venv/bin/rename_engine does not exist and codetools rename works from the installed venv (prove from OUTSIDE the repo: cd /tmp + .venv/bin/codetools rename --help — no PYTHONPATH, the installed artifact).

D3 — tests repointed

• tests/refactor/rename/test_rename_engine_cli.py: repoint the 3 subprocess sites from .venv/bin/rename_engine to .venv/bin/codetools with ["rename", …] args, preserving every assertion INCLUDING the path-traversal security test and the subprocess-entry coverage (the point of this file). Update its docstring: the seam is now the dispatcher verb.
• test_rename_engine_coverage.py / test_executor.py: update the stale rename_engine docstring refs only — no assertion changes.
• Acceptance: PYTEST_DEBUG_TEMPROOT=/var/tmp .venv/bin/python scripts/run_tests_parallel.py tests/refactor/rename/ -j 8 green; paste the lane output verbatim.

D4 — traceability (RUL-034)

• Measure: grep -rln "rename_engine" src/ tests/ docs/ specs/ pyproject.toml must end at ZERO (docstrings updated in D3; the historical provenance lives in git, not in live strings).
• Check codetools --help's verb list and any verbs documentation page for a place that must now mention rename; if a docs/checklist page documents the console-script seam, update it to the verb seam. Paste what you found; if nothing references the seam, say so with the grep output.

D5 — verification lanes (verbatim outputs in the final report)

uv sync --dev --no-editable
PYTEST_DEBUG_TEMPROOT=/var/tmp .venv/bin/python scripts/run_tests_parallel.py tests/refactor/rename/ -j 8
PYTEST_DEBUG_TEMPROOT=/var/tmp .venv/bin/python scripts/run_tests_parallel.py tests/verbs/ -j 8   # if it exists
.venv/bin/codetools --help && .venv/bin/codetools rename --help

No pytest-xdist. No full-tree runs. No test run twice against the same code state.

Fence

ALLOWED (the only paths you may write, repo-relative):

• src/codetools/refactor/cli.py (new) · src/codetools/refactor/rename/cli.py
• pyproject.toml · tests/refactor/rename/test_rename_engine_cli.py
• tests/refactor/rename/test_rename_engine_coverage.py · tests/refactor/rename/test_executor.py
• docs/checklists pages ONLY if D4's measurement proves they name the seam (name them in the report). FORBIDDEN (named): src/codetools/review/** (REV-3 lane ACTIVE), uv.lock, deploy/**, anything not allowlisted — INCLUDING /tmp and every other absolute path (the previous packet's worker was fence-refused on a /tmp helper write; the fence wins every time). FOREIGN DIRT — do not touch/stage/"fix": src/codetools/review/gates.py (M), tests/review/test_review_ruff_lookup.py (??), plans/ast-*.json (M), kimi-export-*.md, plans/*.warmcache.

Conduct

• RUL-037: no python -c/heredoc writes; edit only through your file tools. No codemod scripts.
• Measure before editing; paste verbatim outputs for every claim; no false attribution (L2/L11/L19).
• Do NOT commit — the coordinator verifies and commits with explicit pathspecs.
• The staleness guard fires until you re-sync: that refusal IS the guard working, not a reason to work around it. If the guard refuses a run you believe should pass, STOP and report.
• Final report ends with: git status of the allowlist files, git diff --stat uv.lock (must be empty), the D5 outputs verbatim.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks