feat(#607): rebuild get-shit-done-cc → gsd-core migration (per-package cache + installer auto-cleanup + --dry-run) (#611)

* feat(#607): rebuild get-shit-done-cc → gsd-core migration Leftover get-shit-done-cc installs poisoned the shared update cache, causing a permanent false "update available". Rebuild the migration so a stale old install is both harmless and actively removed. - Per-package update cache filename (gsd-update-check-<slug>.json) in the shared ~/.cache/gsd dir, single-sourced via package-identity; writers stamp package_name and readers reject foreign/absent lineage. Multi- runtime visibility preserved (same shared dir + filename across runtimes). - New get-shit-done/bin/lib/legacy-cleanup.cjs seam: detects code-file references to the old package + the legacy fixed-name cache across home runtime dirs; installer auto-cleans on every install; --dry-run previews and mutates nothing. User hooks and dev-preferences are never touched. - update.md cache-clear globs gsd-update-check*.json across ALL supported runtimes (adds cursor/windsurf/augment/trae/qwen/hermes/codebuddy/cline). - Fix worker MODULE_NOT_FOUND post-install (ship managed-hooks-registry.cjs + degrade gracefully) so the per-package cache is always written. - Diataxis how-to: docs/cleanup-get-shit-done-cc.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(#607): add changeset for PR #611 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(#607): set USERPROFILE alongside HOME in dry-run install test for Windows os.homedir() reads USERPROFILE on win32, so HOME-only isolation let the spawned installer scan the real runner home on windows-latest. Set both. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-02 12:19:57 -04:00
parent df04aae5e4
commit 91f5bd7cb1
26 changed files with 1546 additions and 75 deletions
--- a/docs/INVENTORY-MANIFEST.json
+++ b/docs/INVENTORY-MANIFEST.json
@@ -1,5 +1,5 @@
 {
-  "generated": "2026-06-01",
+  "generated": "2026-06-02",
  "families": {
    "agents": [
      "gsd-advisor-researcher",
@@ -297,6 +297,7 @@
      "installer-migrations.cjs",
      "intel.cjs",
      "learnings.cjs",
+      "legacy-cleanup.cjs",
      "milestone.cjs",
      "model-catalog.cjs",
      "model-profiles.cjs",
--- a/docs/INVENTORY.md
+++ b/docs/INVENTORY.md
@@ -366,7 +366,7 @@ The `gsd-planner` agent is decomposed into a core agent plus reference modules t

 ---

-## CLI Modules (81 shipped)
+## CLI Modules (82 shipped)

 Full listing: `get-shit-done/bin/lib/*.cjs`.

@@ -408,6 +408,7 @@ Full listing: `get-shit-done/bin/lib/*.cjs`.
 | `installer-migrations.cjs` | Installer migration planning, artifact classification, install-state persistence, journaled apply, and rollback helpers |
 | `intel.cjs` | Codebase intel store backing `/gsd-map-codebase --query` and `gsd-intel-updater` |
 | `learnings.cjs` | Cross-phase learnings extraction for `/gsd-extract-learnings` |
+| `legacy-cleanup.cjs` | Detect and remove leftover get-shit-done-cc artifacts; exports `planLegacyCleanup` (pure scan) and `applyLegacyCleanup` (thin IO applier) that root out stale files from the old package across every GSD-managed runtime config directory (#607) |
 | `milestone.cjs` | Milestone archival, requirements marking |
 | `model-catalog.cjs` | CJS adapter over the shared model catalog JSON; exports canonical runtime tier defaults, agent profile maps, alias maps, and routing metadata for all CLI consumers |
 | `model-profiles.cjs` | Backward-compatible profile helpers derived from `model-catalog.cjs`; no longer owns its own model table |
--- a/docs/README.md
+++ b/docs/README.md
@@ -32,6 +32,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
 - [Drive GSD from a tracker issue](how-to/drive-gsd-from-a-tracker-issue.md) — start a phase from a GitHub, Linear, or Jira issue
 - [Migrate from GSD 2](how-to/migrate-from-gsd-2.md) — upgrade an existing GSD 2 project to GSD Core
 - [Update GSD](how-to/update-gsd.md) — re-run the installer to pick up the latest release
+- [Clean up get-shit-done-cc](cleanup-get-shit-done-cc.md) — remove leftover old-package artifacts that cause a spurious `⬆ /gsd:update` indicator after migrating to `@opengsd/gsd-core`
 - [Recover and troubleshoot](how-to/recover-and-troubleshoot.md) — fix common problems, rebuild context, and uninstall

 ---
--- a/docs/cleanup-get-shit-done-cc.md
+++ b/docs/cleanup-get-shit-done-cc.md
@@ -0,0 +1,98 @@
+# Cleaning Up get-shit-done-cc
+
+Use this procedure when you see a persistent `⬆ /gsd:update` indicator in
+your statusline even though `@opengsd/gsd-core` is already up to date.  It
+removes leftover files from the old `get-shit-done-cc` package that was
+renamed to `@opengsd/gsd-core` in issue [#607](https://github.com/open-gsd/gsd-core/issues/607).
+
+## Why this happens
+
+When the package was renamed, its version counter reset — `get-shit-done-cc`
+reached `1.42.x` while `@opengsd/gsd-core` started at `1.2.0`.  If the old
+package is still installed in any runtime config directory (e.g. `~/.gemini`),
+its update checker writes a higher `latest` version into the shared update
+cache (`~/.cache/gsd/gsd-update-check.json`), and older versions of the new
+tooling accepted those foreign writes.  The statusline then permanently shows
+an upgrade that does not exist.  The current installer detects and removes
+these leftovers automatically, and the update cache is now per-package with a
+`package_name` lineage field that readers validate — so a foreign package can
+no longer poison it.
+
+## Steps
+
+### 1. Preview the cleanup (dry run)
+
+Run the installer with `--dry-run` to see exactly what it would change without
+touching anything:
+
+```bash
+npx -y --package=@opengsd/gsd-core@latest -- gsd-core --claude --global --dry-run
+```
+
+The command prints the removal plan — each file path and the reason it would
+be deleted — and lists any stale update-cache files it would clear, then exits
+without making any modifications.
+
+Swap `--claude` for the flag matching your runtime if you use a different one
+(see the [runtime flags table](manual-update.md#runtime-flags)).
+
+### 2. Apply the cleanup
+
+Run the same installer without `--dry-run`:
+
+```bash
+npx -y --package=@opengsd/gsd-core@latest -- gsd-core --claude --global
+```
+
+The installer:
+
+- Detects leftover `get-shit-done-cc` artifacts across all runtime config
+  directories (`~/.claude`, `~/.gemini`, `~/.codex`, `~/.config/opencode`,
+  `~/.kilo`, and others).
+- Removes orphaned hooks, commands, and any file that references the old
+  package name.
+- Clears the stale shared update cache.
+- Preserves user-owned artifacts such as `dev-preferences.md`, custom agents,
+  and any file not managed by GSD.
+
+### 3. Manual fallback
+
+If the installer cannot resolve `get-shit-done-cc` in your environment, or you
+prefer to clean up by hand:
+
+1. **Check each runtime config directory** for a `get-shit-done/` subtree left
+   by the old package:
+
+   ```bash
+   ls ~/.claude/get-shit-done/
+   ls ~/.gemini/get-shit-done/
+   ls ~/.codex/get-shit-done/
+   ls ~/.config/opencode/get-shit-done/
+   ls ~/.kilo/get-shit-done/
+   ```
+
+   Remove any directories found there that were written by `get-shit-done-cc`
+   (the new package installs under the same path, so only remove the directory
+   if you have not yet run the new installer for that runtime).
+
+2. **Uninstall the old package** if it is still resolvable:
+
+   ```bash
+   npx get-shit-done-cc --uninstall
+   ```
+
+3. **Delete the stale shared cache**:
+
+   ```bash
+   rm -f ~/.cache/gsd/gsd-update-check.json
+   ```
+
+### 4. Verify
+
+Open a new terminal session (or restart your AI runtime).  The `⬆ /gsd:update`
+indicator should no longer appear in the statusline.  You can confirm the
+installed version with:
+
+```bash
+npx @opengsd/gsd-core@latest -- gsd-core --version
+```