upgrade-the-loop

the-loop: upgrade-the-loop

Updating the plugin from the marketplace does not guarantee that a project has all the files (or the latest schema) that the current version of the-loop needs. This command reconciles them.

Steps

1. Read versions. Compare theLoopVersion in the project's .the-loop/manifest.yaml with the plugin's version (${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json; in Cursor, .cursor-plugin/plugin.json under the plugin's install directory — ${CLAUDE_PLUGIN_ROOT} below means that same plugin root).

2. Reconcile files. Using ${CLAUDE_PLUGIN_ROOT}/.the-loop/manifest.yaml as the source of truth:

   • Create any missing managed files / directories.
   • Never clobber user-owned files (managed: false) — diff and suggest changes instead.
   • Templates and config schemas are internal to the-loop and are not materialized in the project; read them from ${CLAUDE_PLUGIN_ROOT}/skills/the-loop/templates/ (manifest.templatesDir) and ${CLAUDE_PLUGIN_ROOT}/.the-loop/*.schema.json (manifest.schemasDir) rather than creating a .the-loop/templates/ folder or a .the-loop/*.schema.json copy (issue-220).

3. Clean up deprecated paths. For each entry under manifest.deprecated, if the path is present in the project, act on it — this is how projects initialized by older versions shed the duplicated, internal-only artifacts: .the-loop/templates/, superseded by the plugin's own skill templates (issue #36), and the three .the-loop/*.schema.json copies, superseded by the plugin's own schemas (issue #220 — up to 118 KB of the-loop's internals per repository). Read the entry's reason first: an entry whose reason describes a MIGRATION (e.g. .the-loop/config.yaml, renamed in issue-82) is never deleted here — it is handled by step 4's rename migration, which preserves the data; only remove a path whose reason marks it as safe-to-delete. If a user has clearly added their own files under a deprecated path, surface them in the report and confirm before deleting rather than removing silently.

   • Only the exact paths the manifest names. A candidate that resolves outside the project's .the-loop/ directory — a symlink, a .. segment, an absolute path — is refused and reported, never deleted. Removal is name-driven; it is never inferred from a pattern.
   • A schema copy that differs from the plugin's shipped schema is a signal. Diff it before removing and say so in the report — somebody may have been relying on a local edit, and this is their one chance to find out. If you cannot establish that a file is a the-loop schema copy, leave it and report it under needs-user.