# Tool Rename Migration Plan

Status: draft. Scope: docs/design only. No source, prompt, manifest, or test changes were made for this draft.

## Goals

1. Align common file/shell names with Claude-Code-trained expectations without losing SF's DB-backed semantics.
2. Collapse milestone/slice/task CRUD pairs into lower-schema facades while preserving old names through a compatibility window.
3. Add lazy loading for uncommon tools without hiding mandatory completion/planning tools from autonomous units.

## Phase 1: Add Aliases And Facades

Add aliases and new facades while preserving every old tool name.

Required lockstep files:

- `src/resources/extensions/sf/extension-manifest.json` — add aliases/facades and any `lazy: true` metadata shape.
- `src/resources/extensions/sf/bootstrap/db-tools.js` — register `milestone`, `slice`, `task`, and `requirements` facades that delegate to the existing handlers.
- `src/resources/extensions/sf/bootstrap/exec-tools.js` — route `run_command` compatibility through the canonical shell tool decision; preserve history/search semantics.
- `src/resources/extensions/sf/bootstrap/dynamic-tools.js` — decide whether `Bash`/`Read`/`Edit`/`Write` are true aliases or prompt-only labels over lowercase tools.
- `packages/coding-agent/src/core/tools/find.ts` and `packages/coding-agent/src/core/tools/index.ts` — add `glob`/`Glob` alias for the existing `find` implementation if aliases live in core.
- `packages/coding-agent/src/core/tools/hashline-read.ts`, `packages/coding-agent/src/core/tools/hashline-edit.ts`, `packages/coding-agent/src/core/agent-session.ts` — fold hashline behavior behind normal `read`/`edit` names before retiring `hashline_edit` registry exposure.
- `packages/coding-agent/src/core/system-prompt.ts` — show canonical names and alias guidance in the Available tools section.
- `packages/coding-agent/src/core/extensions/types.ts` — extend tool metadata if `aliases`, `canonicalName`, or `lazy` are schema-level fields.
- `packages/coding-agent/src/core/extensions/loader.ts` — register aliases without clobbering canonical tools and preserve compatibility metadata.
- `packages/coding-agent/src/core/tools/tool-compatibility-registry.ts` — copy compatibility from canonical names to aliases.
- `src/resources/extensions/sf/bootstrap/register-hooks.js` — update guard lists that check planning/completion tool names.
- `src/resources/extensions/sf/workflow-reconcile.js` and `src/resources/extensions/sf/workflow-tools.js` — accept both old and facade names for workflow state transitions.
- `src/headless-ui.ts` and `src/tests/headless-progress.test.ts` — summarize old names and new aliases.
- `src/resources/extensions/sf/tools/workflow-tool-executors.js` — include facade operation names in operation details and errors.
- `src/resources/extensions/sf/prompts/*.md` and `src/resources/extensions/sf/skills/**/*.md` — do not rewrite yet; only add compatibility notes if needed.

Phase 1 acceptance:

- Old prompts continue working unchanged.
- New aliases/facades are visible to the model.
- Tool execution events record both `name` and `canonicalName` where possible.

## Phase 2: Deprecation Banners And Prompt Rewrite

Rewrite all SF-authored prompts, skills, and docs to canonical names. Keep old tools registered, but return a short deprecation note in tool output or UI details when an old name is used.

Required lockstep files:

- `src/resources/extensions/sf/prompts/complete-task.md` if present in generated resources, plus `src/resources/extensions/sf/prompts/execute-task.md` — replace `complete_task` with `task { op: "complete" }` after the facade is proven.
- `src/resources/extensions/sf/prompts/complete-slice.md` — replace `complete_slice`.
- `src/resources/extensions/sf/prompts/complete-milestone.md` — replace `complete_milestone`.
- `src/resources/extensions/sf/prompts/plan-milestone.md`, `guided-plan-milestone.md`, `discuss.md`, `discuss-headless.md` — replace `plan_milestone`, `new_milestone_id`, and follow-on `plan_slice` language.
- `src/resources/extensions/sf/prompts/plan-slice.md`, `guided-plan-slice.md`, `refine-slice.md` — replace `plan_slice`.
- `src/resources/extensions/sf/prompts/replan-slice.md` — replace `replan_slice`.
- `src/resources/extensions/sf/prompts/reassess-roadmap.md`, `validate-milestone.md` — keep `milestone_status` explicit; replace mutation tools only after the read/write split is clear.
- `src/resources/extensions/sf/prompts/research-slice.md`, `research-milestone.md` — update forbidden-tool lists.
- `src/resources/extensions/sf/prompts/autonomous-executor-contract.md` and `autonomous-solver-contract.md` — update mandatory completion/checkpoint language.
- `src/resources/extensions/sf/bootstrap/system-context.js` — update tool guidance and MCP examples without changing MCP names.
- `src/resources/extensions/sf/skills/**/SKILL.md` — sync any tool name examples.
- `docs/**/*.md` user/developer docs that mention old names.
- `tests/**/*.test.*` and `src/resources/extensions/sf/tests/**/*.mjs` fixtures that assert exact tool names.

Phase 2 acceptance:

- Repo prompts no longer teach old names.
- Old names still execute and emit deprecation metadata.
- Traces, UI, and workflow reconciler show canonical names while preserving old-name audit evidence.

## Phase 3: Remove Old Names

Remove old names only after at least one release cycle with clean telemetry and no prompt references.

Required lockstep files:

- `src/resources/extensions/sf/extension-manifest.json` — remove old names and keep canonical facades.
- `src/resources/extensions/sf/bootstrap/db-tools.js` — delete old direct registrations after facade parity.
- `src/resources/extensions/sf/bootstrap/exec-tools.js` — remove `run_command` only if `bash` fully preserves context-mode gating, output history, and `read_output` replacement.
- `packages/coding-agent/src/core/tools/index.ts` and `packages/coding-agent/src/core/sdk.ts` — remove `find`/hashline registry aliases only if all supported providers can call the new names.
- `packages/coding-agent/src/core/system-prompt.ts` — remove old-name deprecation language.
- `src/resources/extensions/sf/bootstrap/register-hooks.js`, `workflow-reconcile.js`, `workflow-tools.js`, `src/headless-ui.ts` — remove fallback cases.
- `tests/**`, `src/resources/extensions/sf/tests/**`, and `docs/**` — remove old-name fixture allowances.

Phase 3 acceptance:

- Forbidden-name guard passes.
- No active prompts, skills, docs, tests, or workflow guards reference removed names except in migration docs.
- Existing traces remain readable via historical renderer mapping.

## CI Guard Design

Add a smoke script such as `scripts/check-tool-name-migration.mjs` with three modes:

- `phase1`: fail only if a new prompt/doc introduces an old name outside an allowlist.
- `phase2`: fail on old names in `src/resources/extensions/sf/prompts/`, `src/resources/extensions/sf/skills/`, `docs/user-docs/`, and `docs/specs/`, except migration docs.
- `phase3`: fail on old names anywhere under `src/`, `packages/`, `tests/`, or `docs/`, except trace-history render maps and explicit migration notes.

Suggested forbidden-name list for phase 2/3:

```js
[
  "run_command",
  "hashline_edit",
  "hashline_read",
  "find",
  "plan_milestone",
  "complete_milestone",
  "validate_milestone",
  "plan_slice",
  "replan_slice",
  "complete_slice",
  "skip_slice",
  "plan_task",
  "complete_task",
  "save_requirement",
  "update_requirement",
  "new_milestone_id"
]
```

The guard should scan text with token boundaries, report file:line, and require an inline marker such as `tool-name-migration-allow` for intentional historical mentions.

## Risk Assessment

High risks:

- Autonomous completion breakage if `complete_task` is hidden before prompts and post-unit logic move together.
- DB-backed planning corruption if `plan_milestone`, `plan_slice`, or `replan_slice` facade schemas are less strict than existing tools.
- Shell safety regression if `run_command` folds into `bash` without preserving context-mode policy, output retention, and execution-policy classification.
- Provider confusion if both lowercase and uppercase aliases are advertised equally; aliases should be compatibility wrappers, not duplicate prompt guidance.

Medium risks:

- UI/status regressions where `headless-ui` and renderers summarize old names.
- MCP confusion if `mcp_*` and `mcp__server__tool` adapter names are normalized with SF-owned names.
- Telemetry/history ambiguity if old and new names are not linked by `canonicalName`.

Low risks:

- Lazy-loading `chapter_open`, `chapter_close`, `manage_todos`, and product-audit tools because they have limited direct prompt exposure.
