refactor: address second round of PR review feedback

- Remove dead cache_file/cache_metadata_file attributes from IntegrationCatalog
- Deduplicate non-default catalog warning (show once per process)
- Anchor version regex to reject partial matches like 1.0.0beta
- Fix 'Preserved modified' message to 'Skipped' for accuracy
- Make upgrade transactional: install new files first, then remove stale
  old-only files, so a failed setup leaves old integration intact
- Update CONTRIBUTING.md: speckit_version validates presence only

Author: mnriem

integrations/CONTRIBUTING.md

@@ -80,7 +80,7 @@ provides:
 | `schema_version` | Must be `"1.0"` |
 | `integration.id` | Lowercase alphanumeric + hyphens (`^[a-z0-9-]+$`) |
 | `integration.version` | Valid semantic version |
-| `requires.speckit_version` | PEP 440 version specifier |
+| `requires.speckit_version` | Required field; current validation checks presence only |
 | `provides` | Must include at least one command or script |
 | `provides.commands[].name` | String identifier |
 | `provides.commands[].file` | Relative path to template file |

src/specify_cli/__init__.py

@@ -2286,15 +2286,8 @@ def integration_upgrade(
 
     selected_script = _resolve_script_type(project_root, script)
 
-    # Phase 1: Teardown old files
+    # Phase 1: Install new files (overwrites existing; old-only files remain)
     console.print(f"Upgrading integration: [cyan]{key}[/cyan]")
-    removed, skipped = old_manifest.uninstall(project_root, force=force)
-    if removed:
-        console.print(f"  Removed {len(removed)} old file(s)")
-    if skipped:
-        console.print(f"  [yellow]Preserved {len(skipped)} modified file(s)[/yellow]")
-
-    # Phase 2: Reinstall
     new_manifest = IntegrationManifest(key, project_root, version=get_speckit_version())
 
     parsed_options: dict[str, Any] | None = None
@@ -2319,15 +2312,33 @@ def integration_upgrade(
             console.print(
                 f"[yellow]Warning:[/yellow] Teardown during rollback also failed: {teardown_exc}"
             )
-        # Attempt to restore the old manifest so the project is not left broken
-        try:
-            old_manifest.save()
-            _write_integration_json(project_root, key, selected_script)
-        except Exception:
-            pass  # Best-effort restoration; original error is more important
         console.print(f"[red]Error:[/red] Failed to upgrade integration: {exc}")
         raise typer.Exit(1)
 
+    # Phase 2: Remove stale files from old manifest that are not in the new one
+    old_files = set(old_manifest.files.keys())
+    new_files = set(new_manifest.files.keys())
+    stale_files = old_files - new_files
+    stale_removed = 0
+    for rel in stale_files:
+        path = project_root / rel
+        if path.exists() and path.is_file():
+            try:
+                path.unlink()
+                stale_removed += 1
+                # Clean up empty parent directories up to project root
+                parent = path.parent
+                while parent != project_root:
+                    try:
+                        parent.rmdir()
+                    except OSError:
+                        break
+                    parent = parent.parent
+            except OSError:
+                pass
+    if stale_removed:
+        console.print(f"  Removed {stale_removed} stale file(s) from previous install")
+
     name = (integration.config or {}).get("name", key)
     console.print(f"\n[green]✓[/green] Integration '{name}' upgraded successfully")
 

src/specify_cli/integrations/catalog.py

@@ -66,8 +66,6 @@ class IntegrationCatalog:
     def __init__(self, project_root: Path) -> None:
         self.project_root = project_root
         self.cache_dir = project_root / ".specify" / "integrations" / ".cache"
-        self.cache_file = self.cache_dir / "catalog.json"
-        self.cache_metadata_file = self.cache_dir / "catalog-metadata.json"
 
     # -- URL validation ---------------------------------------------------
 
@@ -176,11 +174,13 @@ def get_active_catalogs(self) -> List[IntegrationCatalogEntry]:
         if env_value:
             self._validate_catalog_url(env_value)
             if env_value != self.DEFAULT_CATALOG_URL:
-                print(
-                    "Warning: Using non-default integration catalog. "
-                    "Only use catalogs from sources you trust.",
-                    file=sys.stderr,
-                )
+                if not getattr(self, "_non_default_catalog_warning_shown", False):
+                    print(
+                        "Warning: Using non-default integration catalog. "
+                        "Only use catalogs from sources you trust.",
+                        file=sys.stderr,
+                    )
+                    self._non_default_catalog_warning_shown = True
             return [
                 IntegrationCatalogEntry(
                     url=env_value,
@@ -459,7 +459,7 @@ def _validate(self) -> None:
                 "must be lowercase alphanumeric with hyphens only"
             )
 
-        if not re.match(r"^\d+\.\d+\.\d+", integ["version"]):
+        if not re.match(r"^\d+\.\d+\.\d+$", integ["version"]):
             raise IntegrationDescriptorError(
                 f"Invalid version '{integ['version']}': must use semantic versioning (e.g., 1.0.0)"
             )