Skip to content

Align tool, command, and flag names with plannotator - #2

Merged
a4180p merged 1 commit into
mainfrom
plannotator-naming-parity
Sep 8, 2026
Merged

a4180p merged 1 commit into
mainfrom
plannotator-naming-parity

Conversation

@a4180p

@a4180p a4180p commented Sep 8, 2026

Copy link
Copy Markdown
Owner

Context

@plannotator/pi-extension ships a pi plan mode that overlaps this extension almost entirely — identical Phase union, an equivalent plan-submit tool, the same [DONE:n] protocol, and functions literally named parseChecklist / markCompletedSteps. This adopts its naming convention so the two are distinguishable when both are installed, and matches its write gate and review-outcome model as far as revdiff can express it.

Renames

Kind From To
Tool plan_submit revdiff_submit_plan
Tool mark_done revdiff_mark_done
Command /plan /revdiff-plan-mode
Command /plan-abort /revdiff-plan-abort
Command /plan-status /revdiff-plan-status
Flag --plan --revdiff-plan

The flag rename is not cosmetic: plannotator registers its own --plan, so the old name collided.

Prompt and error strings were updated in lockstep — otherwise the agent gets told to call a tool that no longer exists.

Migration. stripPlanTools filters the pre-rename names alongside the current ones at every site that rebuilds the tool list, so a session persisted by an earlier version cannot carry a stale plan_submit into a restored list.

Write gate

Dropped the isAbsolute early return from isPlanPathAllowed, matching plannotator's isPlanWritePathAllowed. An absolute path is now judged purely by containment, so one pointing inside cwd is accepted. Paths outside cwd are still rejected by the existing path.relative check.

This deliberately inverts an existing assertion in test/parsing.test.ts; the test now also pins the outside-cwd case that actually matters.

Review outcomes

revdiff exposes two signals only — exit 0 (clean quit) and exit 10 (--exit-code-on-annotations). Everything else was previously folded into the deny path:

return { approved: false, annotations: `revdiff exited with code ${exitCode}` };

The agent read that as plan feedback and would try to revise the plan in response to a crash. Following plannotator's classifyAnnotateOutcome, a session that ends without a decision is now its own outcome and tells the agent to resubmit.

Classification moved into an exported pure classifyReviewOutcome(launchError, exitCode, rawOutput), which makes the three-way result testable without driving the TUI.

Not implemented: approve-with-notes. Verified against revdiff v1.13.0 — --help and --dump-keys show q (quit, flushes annotations), Q (discard_quit), and O (flush_output). There is no flag or key that distinguishes annotating-and-approving from annotating-and-denying, so plannotator's approved-with-feedback case cannot be represented. Related: Q discard-quit is indistinguishable from a genuine clean approve (both exit 0 with empty output).

Verification

npm run validate — 11/11 passing (8 pre-existing + 3 new).

Warning

npm test runs against dist/, and tsc never prunes deleted files from it, so stale compiled tests keep running and inflate the count. Run rm -rf dist first. A clean step in build would be a worthwhile follow-up.

Out of scope

  • import { Type } from "typebox" is unlisted in package.json — pre-existing on main, flagged not fixed.
  • readme.md's project structure lists test/keywords.test.ts, which doesn't exist on main.

`@plannotator/pi-extension` ships an overlapping pi plan mode. Adopt its
naming convention so the two are distinguishable, and match its write gate
and review-outcome model where revdiff can express it.

Renames:
- `plan_submit` -> `revdiff_submit_plan`
- `mark_done` -> `revdiff_mark_done`
- `/plan` -> `/revdiff-plan-mode`
- `/plan-abort` -> `/revdiff-plan-abort`
- `/plan-status` -> `/revdiff-plan-status`
- `--plan` -> `--revdiff-plan`, avoiding a collision with plannotator's
  own `--plan` flag

Add `stripPlanTools`, which filters the pre-rename names alongside the
current ones so a session persisted by an earlier version cannot carry a
stale `plan_submit` into a restored tool list.

Drop the `isAbsolute` early return from `isPlanPathAllowed` to match
plannotator's `isPlanWritePathAllowed`: an absolute path is now judged by
containment, so one pointing inside cwd is allowed.

Add a third review outcome. revdiff exposes two signals only, exit 0 for a
clean quit and exit 10 for annotations, so a crash, a signal, or a missing
binary previously reached the agent as fabricated plan feedback and invited
it to revise the plan in response to an error. Classification moves into an
exported pure `classifyReviewOutcome`, and a session that ended without a
decision now tells the agent to resubmit instead.

Approve-with-notes is deliberately not implemented: revdiff has no signal
that distinguishes annotating-and-approving from annotating-and-denying.
@a4180p
a4180p merged commit 4a43e1d into main Sep 8, 2026
1 of 2 checks passed
@a4180p
a4180p deleted the plannotator-naming-parity branch September 8, 2026 12:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant