half-orm-dev 0.17.5a2__tar.gz → 0.17.5a4__tar.gz

{half_orm_dev-0.17.5a2/half_orm_dev.egg-info → half_orm_dev-0.17.5a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: half_orm_dev
-Version: 0.17.5a2
+Version: 0.17.5a4
 Summary: half_orm development Framework.
 Author-email: Joël Maïzi <joel.maizi@collorg.org>
 License-Expression: GPL-3.0-or-later

{half_orm_dev-0.17.5a2 → half_orm_dev-0.17.5a4}/half_orm_dev/bootstrap_manager.py

@@ -78,7 +78,12 @@ class BootstrapManager:
             # Schema might not exist yet, ignore
             pass
 
-    def get_bootstrap_files(self, up_to_version: Optional[str] = None) -> List[Path]:
+    def get_bootstrap_files(
+        self,
+        up_to_version: Optional[str] = None,
+        exclude_version: Optional[str] = None,
+        for_version: Optional[str] = None
+    ) -> List[Path]:
         """
         List bootstrap files sorted by numeric prefix.
 
@@ -87,8 +92,11 @@ class BootstrapManager:
 
         Args:
             up_to_version: If provided, only return files with version <= this version.
-                          Used during restore_database_from_schema to avoid executing
-                          bootstraps for future releases.
+            exclude_version: If provided, exclude files for exactly this version.
+                            Used during promote to skip the version being promoted
+                            (its bootstraps run after patches are applied).
+            for_version: If provided, only return files for exactly this version.
+                        Used after patches to run only the promoted version's bootstraps.
 
         Returns:
             List of Path objects for bootstrap files in execution order
@@ -103,11 +111,20 @@ class BootstrapManager:
                 if not re.match(r'^\d+-', file_path.name):
                     continue
 
-                # If up_to_version is specified, filter out files from newer versions
-                if up_to_version:
-                    file_version = self._extract_version_from_filename(file_path.name)
-                    if file_version != 'unknown' and not self._version_le(file_version, up_to_version):
+                file_version = self._extract_version_from_filename(file_path.name)
+
+                # If for_version is specified, only include files for exactly this version
+                if for_version:
+                    if file_version != for_version:
+                        continue
+                else:
+                    # If exclude_version is specified, skip files for that version
+                    if exclude_version and file_version == exclude_version:
                         continue
+                    # If up_to_version is specified, filter out files from newer versions
+                    if up_to_version:
+                        if file_version != 'unknown' and not self._version_le(file_version, up_to_version):
+                            continue
 
                 files.append(file_path)
 
@@ -140,17 +157,24 @@ class BootstrapManager:
             # Table might not exist yet (pre-migration)
             return set()
 
-    def get_pending_files(self, up_to_version: Optional[str] = None) -> List[Path]:
+    def get_pending_files(
+        self,
+        up_to_version: Optional[str] = None,
+        exclude_version: Optional[str] = None,
+        for_version: Optional[str] = None
+    ) -> List[Path]:
         """
         Get bootstrap files not yet executed.
 
         Args:
             up_to_version: If provided, only return files with version <= this version.
+            exclude_version: If provided, exclude files for exactly this version.
+            for_version: If provided, only return files for exactly this version.
 
         Returns:
             List of Path objects for files pending execution
         """
-        all_files = self.get_bootstrap_files(up_to_version)
+        all_files = self.get_bootstrap_files(up_to_version, exclude_version=exclude_version, for_version=for_version)
         executed = self.get_executed_files()
 
         return [f for f in all_files if f.name not in executed]
@@ -201,7 +225,9 @@ class BootstrapManager:
         dry_run: bool = False,
         force: bool = False,
         exclude_patch_id: Optional[str] = None,
-        up_to_version: Optional[str] = None
+        up_to_version: Optional[str] = None,
+        exclude_version: Optional[str] = None,
+        for_version: Optional[str] = None
     ) -> dict:
         """
         Execute pending bootstrap files.
@@ -215,6 +241,8 @@ class BootstrapManager:
             up_to_version: If provided, only execute files with version <= this version.
                           Used during restore_database_from_schema to avoid executing
                           bootstraps for future releases.
+            exclude_version: If provided, exclude files for exactly this version.
+            for_version: If provided, only execute files for exactly this version.
 
         Returns:
             Dict with execution results:
@@ -231,11 +259,11 @@ class BootstrapManager:
         }
 
         if force:
-            files_to_execute = self.get_bootstrap_files(up_to_version)
+            files_to_execute = self.get_bootstrap_files(up_to_version, exclude_version=exclude_version, for_version=for_version)
         else:
-            files_to_execute = self.get_pending_files(up_to_version)
+            files_to_execute = self.get_pending_files(up_to_version, exclude_version=exclude_version, for_version=for_version)
             # Calculate skipped
-            all_files = self.get_bootstrap_files(up_to_version)
+            all_files = self.get_bootstrap_files(up_to_version, exclude_version=exclude_version, for_version=for_version)
             executed = self.get_executed_files()
             result['skipped'] = [f.name for f in all_files if f.name in executed]
 

{half_orm_dev-0.17.5a2 → half_orm_dev-0.17.5a4}/half_orm_dev/cli/commands/check.py

@@ -153,6 +153,14 @@ def _display_check_results(repo, result: dict, dry_run: bool, verbose: bool):
     elif verbose:
         click.echo(f"\n📦 {utils.Color.bold('Active releases:')} None")
 
+    # Show orphaned patches
+    orphaned_patches = result.get('orphaned_patches', [])
+    if orphaned_patches:
+        click.echo(f"\n🔧 {utils.Color.bold('Orphaned patches')} ({len(orphaned_patches)}):")
+        for patch_id in sorted(orphaned_patches):
+            click.echo(f"  • {patch_id}")
+        click.echo(f"  {utils.Color.blue('(Use \"half_orm dev release attach-patch <id>\" to reattach)')}")
+
     # Show standalone patch branches (not in candidates/stage)
     standalone_patches = [b for b in patch_branches
                          if not _is_patch_in_releases(b['name'], releases_info)]

{half_orm_dev-0.17.5a2 → half_orm_dev-0.17.5a4}/half_orm_dev/cli/commands/patch.py

@@ -5,6 +5,7 @@ Groups all patch-related commands under 'half_orm dev patch':
 - patch create: Create new patch branch and directory
 - patch apply: Apply current patch files to database
 - patch merge: Add patch to stage release with validation
+- patch detach: Detach a candidate patch from its release
 
 Replaces legacy commands:
 - create-patch → patch create
@@ -365,3 +366,87 @@ def patch_merge(force: bool) -> None:
 
     except PatchManagerError as e:
         raise click.ClickException(str(e))
+
+
+@patch.command('detach')
+@click.argument('patch_id', type=str, required=False)
+@click.option('--force', '-f', is_flag=True, help='Skip confirmation prompt')
+def patch_detach(patch_id: Optional[str], force: bool) -> None:
+    """
+    Detach a candidate patch from its release.
+
+    Moves the patch to Patches/orphaned/ directory.
+    The git branch is preserved for future reattachment.
+
+    If PATCH_ID is not provided, uses the current branch's patch.
+
+    Examples:
+        Detach current patch (from ho-patch/* branch):
+        $ half_orm dev patch detach
+
+        Detach specific patch:
+        $ half_orm dev patch detach 123-feature
+
+        Detach without confirmation:
+        $ half_orm dev patch detach --force
+    """
+    try:
+        repo = Repo()
+
+        # Auto-detect patch_id from current branch if not provided
+        if not patch_id:
+            branch = repo.hgit.branch
+            if not branch.startswith('ho-patch/'):
+                raise click.UsageError(
+                    "Not on a patch branch. Provide PATCH_ID or checkout ho-patch/* branch."
+                )
+            patch_id = branch.replace('ho-patch/', '')
+
+        # Get patch info for confirmation
+        status_map = repo.patch_manager.get_patch_status_map()
+        if patch_id not in status_map:
+            click.echo(utils.Color.red(f"Patch '{patch_id}' not found"))
+            raise click.Abort()
+
+        patch_info = status_map[patch_id]
+        version = patch_info.get('version', 'unknown')
+        status = patch_info.get('status', 'unknown')
+
+        # Check if patch can be detached
+        if status == 'staged':
+            click.echo(utils.Color.red(
+                f"Cannot detach staged patch '{patch_id}'. "
+                "Only candidate patches can be detached."
+            ))
+            raise click.Abort()
+
+        if status == 'orphaned':
+            click.echo(utils.Color.red(f"Patch '{patch_id}' is already orphaned."))
+            raise click.Abort()
+
+        # Confirmation
+        if not force:
+            click.echo(f"Detaching patch '{utils.Color.bold(patch_id)}' from release {utils.Color.bold(version)}")
+            click.echo()
+            click.echo("This will:")
+            click.echo(f"  • Remove patch from {version}-patches.toml")
+            click.echo(f"  • Move directory to Patches/orphaned/{patch_id}/")
+            click.echo(f"  • Keep git branch ho-patch/{patch_id}")
+            click.echo()
+            if not click.confirm("Continue?", default=True):
+                click.echo("Cancelled.")
+                return
+
+        # Execute detach
+        result = repo.patch_manager.detach_patch(patch_id)
+
+        click.echo()
+        click.echo(utils.Color.green(f"✓ Patch '{patch_id}' detached from release {version}"))
+        click.echo(f"  Directory moved to: {result['orphaned_path']}")
+        click.echo(f"  Branch preserved: ho-patch/{patch_id}")
+        click.echo()
+        click.echo("To reattach later: half_orm dev release attach-patch <patch_id>")
+
+    except PatchManagerError as e:
+        click.echo(utils.Color.red(f"Error: {e}"), err=True)
+        raise click.Abort()

{half_orm_dev-0.17.5a2 → half_orm_dev-0.17.5a4}/half_orm_dev/cli/commands/release.py

@@ -4,6 +4,7 @@ Release command group - Unified release management.
 Groups all release-related commands under 'half_orm dev release':
 - release create: Prepare next release stage file
 - release promote: Promote stage to rc or production
+- release attach-patch: Reattach orphaned patch to a release
 """
 
 import click
@@ -16,6 +17,7 @@ from half_orm_dev.release_manager import (
     ReleaseFileError,
     ReleaseVersionError
 )
+from half_orm_dev.patch_manager import PatchManagerError
 from half_orm import utils
 
 
@@ -484,3 +486,65 @@ def release_apply(skip_tests: bool) -> None:
         click.echo(f"❌ {utils.Color.red('Release apply failed:')}", err=True)
         click.echo(f"   {str(e)}", err=True)
         sys.exit(1)
+
+
+@release.command('attach-patch')
+@click.argument('patch_id', type=str)
+@click.option('--force', '-f', is_flag=True, help='Skip confirmation prompt')
+def release_attach_patch(patch_id: str, force: bool) -> None:
+    """
+    Reattach an orphaned patch to the current release.
+
+    Moves the patch from Patches/orphaned/ back to Patches/ and adds it
+    as a candidate in the release TOML file.
+
+    Must be run from a ho-release/X.Y.Z branch.
+
+    \b
+    EXAMPLES:
+        # Reattach an orphaned patch
+        half_orm dev release attach-patch 123-feature
+
+        # Skip confirmation
+        half_orm dev release attach-patch 123-feature --force
+    """
+    try:
+        repo = Repo()
+
+        # Must be on ho-release/* branch
+        current_branch = repo.hgit.branch
+        if not current_branch.startswith('ho-release/'):
+            click.echo(
+                f"❌ {utils.Color.red('Must be on ho-release/X.Y.Z branch.')}",
+                err=True
+            )
+            click.echo(
+                f"   Current branch: {current_branch}",
+                err=True
+            )
+            sys.exit(1)
+
+        version = current_branch.replace('ho-release/', '')
+
+        # Confirmation
+        if not force:
+            click.echo(f"Attaching patch '{patch_id}' to release {version}")
+            click.echo("This will:")
+            click.echo(f"  • Add patch to {version}-patches.toml as candidate")
+            click.echo(f"  • Move directory from Patches/orphaned/{patch_id}/ to Patches/{patch_id}/")
+            if not click.confirm("Continue?", default=True):
+                click.echo("Cancelled.")
+                return
+
+        # Execute attach
+        result = repo.patch_manager.attach_patch(patch_id, version)
+
+        click.echo(utils.Color.green(
+            f"✓ Patch '{patch_id}' attached to release {version}"
+        ))
+        click.echo(f"  Status: candidate")
+        click.echo(f"  Directory: {result['patch_path']}")
+
+    except PatchManagerError as e:
+        click.echo(f"❌ {utils.Color.red(str(e))}", err=True)
+        sys.exit(1)

{half_orm_dev-0.17.5a2 → half_orm_dev-0.17.5a4}/half_orm_dev/decorators.py

@@ -4,6 +4,7 @@ Decorators for half-orm-dev.
 Provides common decorators for ReleaseManager and PatchManager.
 """
 
+import signal
 import sys
 import inspect
 from functools import wraps
@@ -13,9 +14,6 @@ def with_dynamic_branch_lock(branch_getter, timeout_minutes: int = 30):
     """
     Decorator to protect methods with a dynamic branch lock.
 
-    Unlike with_branch_lock which uses a static branch name, this decorator
-    calls a function to determine the branch name at runtime.
-
     IMPORTANT: Automatically syncs .hop/ directory to all other active branches
     after the decorated method completes (from locked branch to all others).
 
@@ -77,8 +75,21 @@ def with_dynamic_branch_lock(branch_getter, timeout_minutes: int = 30):
                 return result
             finally:
                 # Always release lock (even on error)
+                # Block SIGINT during cleanup to prevent Ctrl+C from
+                # interrupting lock release and leaving an orphan tag.
                 if lock_tag:
-                    self._repo.hgit.release_branch_lock(lock_tag)
+                    interrupted = False
+                    original_handler = signal.getsignal(signal.SIGINT)
+                    signal.signal(signal.SIGINT, lambda s, f: setattr(
+                        wrapper, '_interrupted', True) or None)
+                    wrapper._interrupted = False
+                    try:
+                        self._repo.hgit.release_branch_lock(lock_tag)
+                    finally:
+                        interrupted = wrapper._interrupted
+                        signal.signal(signal.SIGINT, original_handler)
+                    if interrupted:
+                        raise KeyboardInterrupt()
 
         return wrapper
     return decorator

{half_orm_dev-0.17.5a2 → half_orm_dev-0.17.5a4}/half_orm_dev/patch_manager.py

@@ -2033,11 +2033,15 @@ class PatchManager:
         # 5. Merge patch branch into release branch
         try:
             self._repo.hgit.merge(patch_branch, message=f'''[HOP] Merge #{patch_id} into %"{version}"''')
-        except Exception as e:
-            raise PatchManagerError(
-                f"Failed to merge {patch_branch} into {release_branch}: {e}\n"
-                f"You may need to resolve conflicts manually."
-            )
+        except (GitCommandError, Exception) as e:
+            # Auto-resolve conflicts in generated files (package dir).
+            # Generated files are regenerated by modules.generate() so
+            # conflicts there can be safely auto-resolved.
+            if not self._auto_resolve_generated_conflicts(e, patch_branch, release_branch):
+                raise PatchManagerError(
+                    f"Failed to merge {patch_branch} into {release_branch}: {e}\n"
+                    f"You may need to resolve conflicts manually."
+                )
 
         # 5b. Get merge commit hash
         merge_commit = self._repo.hgit.last_commit()
@@ -2212,6 +2216,55 @@ class PatchManager:
         # Return to original branch
         self._repo.hgit.checkout(original_branch)
 
+    def _auto_resolve_generated_conflicts(
+        self,
+        merge_error: Exception,
+        patch_branch: str,
+        target_branch: str = None
+    ) -> bool:
+        """
+        Auto-resolve merge conflicts when they only affect generated files.
+
+        Generated files (under the package directory) are regenerated by
+        modules.generate() after patch apply, so conflicts there are harmless
+        and can be safely resolved by accepting either side.
+
+        Args:
+            merge_error: The exception from the failed merge
+            patch_branch: The patch branch being merged
+            target_branch: Optional target branch name (for error messages)
+
+        Returns:
+            True if conflicts were auto-resolved, False otherwise
+        """
+        package_name = self._repo.name
+        git = self._repo.hgit._HGit__git_repo.git
+
+        try:
+            diff_output = git.diff('--name-only', '--diff-filter=U')
+            if not isinstance(diff_output, str) or not diff_output.strip():
+                return False
+            conflicted = diff_output.strip().splitlines()
+        except Exception:
+            return False
+
+        non_generated = [
+            f for f in conflicted
+            if not f.startswith(f"{package_name}/")
+        ]
+
+        if non_generated:
+            return False
+
+        # All conflicts are in generated files — auto-resolve
+        # and conclude the interrupted merge commit.
+        click.echo(f"  • Auto-resolving conflicts in generated files...")
+        for f in conflicted:
+            git.checkout('--theirs', f)
+        git.add(*conflicted)
+        git.commit('--no-verify', '--no-edit')
+        return True
+
     def _validate_patch_before_merge(
         self,
         patch_id: str,
@@ -2267,11 +2320,15 @@ class PatchManager:
             click.echo(f"  • Merging {patch_branch} into temp branch...")
             try:
                 self._repo.hgit.merge(patch_branch, message=f"[VALIDATE] Test merge #{patch_id}")
-            except Exception as e:
-                raise PatchManagerError(
-                    f"Failed to merge {patch_branch} during validation: {e}\n"
-                    f"Please resolve conflicts before closing the patch."
-                )
+            except (GitCommandError, Exception) as e:
+                # Auto-resolve conflicts in generated files (package dir).
+                # Generated files are regenerated by modules.generate() so
+                # conflicts there can be safely auto-resolved.
+                if not self._auto_resolve_generated_conflicts(e, patch_branch):
+                    raise PatchManagerError(
+                        f"Failed to merge {patch_branch} during validation: {e}\n"
+                        f"Please resolve conflicts before closing the patch."
+                    )
 
             # 3. Run patch apply and verify no modifications
             click.echo(f"  • Running patch apply to verify idempotency...")
@@ -2308,18 +2365,31 @@ class PatchManager:
                 # Generate modules
                 modules.generate(self._repo)
 
-                # Check if any files were modified
+                # Stage generated files (package dir) — they are always
+                # regenerated from DB state so changes there are expected.
+                package_name = self._repo.name
+                package_dir = Path(self._repo.base_dir) / package_name
+                if package_dir.exists():
+                    self._repo.hgit.add(str(package_dir))
+
+                # Check if any NON-generated files were modified
                 if not self._repo.hgit.repos_is_clean():
                     modified_files = self._repo.hgit.get_modified_files()
-                    raise PatchManagerError(
-                        f"Patch validation failed: patch apply modified files!\n"
-                        f"This indicates the patch is not idempotent or schema is out of sync.\n\n"
-                        f"Modified files:\n" + "\n".join(f"  • {f}" for f in modified_files) + "\n\n"
-                        f"Actions required:\n"
-                        f"  1. Verify patch SQL is idempotent (uses CREATE IF NOT EXISTS, etc.)\n"
-                        f"  2. Ensure schema.sql is up to date with all previous patches\n"
-                        f"  3. Run 'half_orm dev patch apply' on your patch branch to test"
-                    )
+                    # Filter out generated files (already staged)
+                    non_generated = [
+                        f for f in modified_files
+                        if not f.startswith(f"{package_name}/")
+                    ]
+                    if non_generated:
+                        raise PatchManagerError(
+                            f"Patch validation failed: patch apply modified files!\n"
+                            f"This indicates the patch is not idempotent or schema is out of sync.\n\n"
+                            f"Modified files:\n" + "\n".join(f"  • {f}" for f in non_generated) + "\n\n"
+                            f"Actions required:\n"
+                            f"  1. Verify patch SQL is idempotent (uses CREATE IF NOT EXISTS, etc.)\n"
+                            f"  2. Ensure schema.sql is up to date with all previous patches\n"
+                            f"  3. Run 'half_orm dev patch apply' on your patch branch to test"
+                        )
 
                 click.echo(f"  • {utils.Color.green('✓')} Patch apply succeeded with no modifications")
 
@@ -2361,6 +2431,15 @@ class PatchManager:
         finally:
             # 6. Cleanup: Delete temp branch and return to original branch
             try:
+                # Discard any staged/unstaged changes in the generated package
+                # dir so checkout doesn't fail (they were staged during validation).
+                package_name = self._repo.name
+                try:
+                    self._repo.hgit._HGit__git_repo.git.reset('HEAD', '--', f'{package_name}/')
+                    self._repo.hgit._HGit__git_repo.git.checkout('--', f'{package_name}/')
+                except Exception:
+                    pass
+
                 # Return to original branch
                 if self._repo.hgit.branch != original_branch:
                     self._repo.hgit.checkout(original_branch)
@@ -3005,6 +3084,152 @@ class PatchManager:
                 f"Failed to move patch to staged: {e}"
             )
 
+    def detach_patch(self, patch_id: str) -> dict:
+        """
+        Detach a candidate patch from its release (move to orphaned/).
+
+        Workflow:
+        1. Validate patch is candidate (not staged)
+        2. Remove patch from TOML file
+        3. Move directory to Patches/orphaned/
+        4. Keep git branch as-is (for future reattachment)
+        5. Update cache
+        6. Commit and sync changes
+
+        Args:
+            patch_id: Patch identifier to detach
+
+        Returns:
+            dict with 'patch_id', 'version', 'orphaned_path'
+
+        Raises:
+            PatchManagerError: If patch not found, not candidate, or operation fails
+        """
+        # 1. Get patch status
+        status_map = self.get_patch_status_map()
+        if patch_id not in status_map:
+            raise PatchManagerError(f"Patch '{patch_id}' not found")
+
+        patch_info = status_map[patch_id]
+        status = patch_info.get("status")
+        version = patch_info.get("version")
+
+        # 2. Validate: only candidates can be detached
+        if status == "staged":
+            raise PatchManagerError(
+                f"Cannot detach staged patch '{patch_id}'. "
+                "Only candidate patches can be detached."
+            )
+        if status == "orphaned":
+            raise PatchManagerError(f"Patch '{patch_id}' is already orphaned.")
+
+        # 3. Remove from TOML
+        release_file = ReleaseFile(version, self._releases_dir)
+        release_file.remove_patch(patch_id)
+        self._repo.hgit.add(str(release_file.file_path))
+
+        # 4. Move directory to orphaned/
+        old_path = self.get_patch_directory_path(patch_id)
+        orphaned_dir = self._schema_patches_dir / "orphaned"
+        new_path = orphaned_dir / patch_id
+
+        if old_path.exists():
+            orphaned_dir.mkdir(exist_ok=True)
+            self._repo.hgit.mv(str(old_path), str(new_path))
+
+        # 5. Update cache
+        self._update_patch_status_cache(patch_id, "orphaned")
+
+        # 6. Commit changes (include Patches/ directory in sync)
+        self._repo.commit_and_sync_to_active_branches(
+            message=f"[HOP] detach patch #{patch_id} from release %{version}",
+            files=['Patches/']
+        )
+
+        return {
+            'patch_id': patch_id,
+            'version': version,
+            'orphaned_path': str(new_path)
+        }
+
+    def attach_patch(self, patch_id: str, version: str) -> dict:
+        """
+        Attach an orphaned patch to a release (move from orphaned/ to root).
+
+        Reverse of detach_patch(). Workflow:
+        1. Validate patch is orphaned
+        2. Validate target release exists (TOML file)
+        3. Add patch to TOML as candidate
+        4. Move directory from Patches/orphaned/ to Patches/
+        5. Update cache
+        6. Commit and sync changes
+
+        Args:
+            patch_id: Patch identifier to attach
+            version: Target release version (e.g., "0.1.0")
+
+        Returns:
+            dict with 'patch_id', 'version', 'patch_path'
+
+        Raises:
+            PatchManagerError: If patch not found, not orphaned, or release doesn't exist
+        """
+        # 1. Get patch status
+        status_map = self.get_patch_status_map()
+        if patch_id not in status_map:
+            raise PatchManagerError(f"Patch '{patch_id}' not found")
+
+        patch_info = status_map[patch_id]
+        status = patch_info.get("status")
+
+        # 2. Validate: only orphaned patches can be attached
+        if status == "candidate":
+            raise PatchManagerError(
+                f"Patch '{patch_id}' is already a candidate in release "
+                f"{patch_info.get('version')}."
+            )
+        if status == "staged":
+            raise PatchManagerError(
+                f"Cannot attach staged patch '{patch_id}'. "
+                "Staged patches are already integrated."
+            )
+        if status != "orphaned":
+            raise PatchManagerError(
+                f"Patch '{patch_id}' has unexpected status '{status}'."
+            )
+
+        # 3. Validate release exists and add to TOML
+        release_file = ReleaseFile(version, self._releases_dir)
+        if not release_file.file_path.exists():
+            raise PatchManagerError(
+                f"Release {version} not found. "
+                f"No file {release_file.file_path.name} exists."
+            )
+        release_file.add_patch(patch_id)
+        self._repo.hgit.add(str(release_file.file_path))
+
+        # 4. Move directory from orphaned/ to root
+        orphaned_path = self._schema_patches_dir / "orphaned" / patch_id
+        new_path = self._schema_patches_dir / patch_id
+
+        if orphaned_path.exists():
+            self._repo.hgit.mv(str(orphaned_path), str(new_path))
+
+        # 5. Update cache
+        self._update_patch_status_cache(patch_id, "candidate")
+
+        # 6. Commit changes (include Patches/ directory in sync)
+        self._repo.commit_and_sync_to_active_branches(
+            message=f"[HOP] attach patch #{patch_id} to release %{version}",
+            files=['Patches/']
+        )
+
+        return {
+            'patch_id': patch_id,
+            'version': version,
+            'patch_path': str(new_path)
+        }
+
     def _get_other_candidates(self, version: str, exclude_patch: str) -> List[str]:
         """
         Get list of other candidate patches for a release (excluding one).