crackerjack 0.27.9__py3-none-any.whl → 0.29.0__py3-none-any.whl

crackerjack/crackerjack.py

@@ -37,6 +37,463 @@ class HookResult:
             self.issues_found = []
 
 
+@dataclass
+class TaskStatus:
+    id: str
+    name: str
+    status: str
+    start_time: float | None = None
+    end_time: float | None = None
+    duration: float | None = None
+    details: str | None = None
+    error_message: str | None = None
+    files_changed: list[str] | None = None
+
+    def __post_init__(self) -> None:
+        if self.files_changed is None:
+            self.files_changed = []
+        if self.start_time is not None and self.end_time is not None:
+            self.duration = self.end_time - self.start_time
+
+
+class SessionTracker(BaseModel, arbitrary_types_allowed=True):
+    console: Console
+    session_id: str
+    start_time: float
+    progress_file: Path
+    tasks: dict[str, TaskStatus] = {}
+    current_task: str | None = None
+    metadata: dict[str, t.Any] = {}
+
+    def __init__(self, **data: t.Any) -> None:
+        super().__init__(**data)
+        if not self.tasks:
+            self.tasks = {}
+        if not self.metadata:
+            self.metadata = {}
+
+    def start_task(
+        self, task_id: str, task_name: str, details: str | None = None
+    ) -> None:
+        task = TaskStatus(
+            id=task_id,
+            name=task_name,
+            status="in_progress",
+            start_time=time.time(),
+            details=details,
+        )
+        self.tasks[task_id] = task
+        self.current_task = task_id
+        self._update_progress_file()
+        self.console.print(f"[yellow]⏳[/yellow] Started: {task_name}")
+
+    def complete_task(
+        self,
+        task_id: str,
+        details: str | None = None,
+        files_changed: list[str] | None = None,
+    ) -> None:
+        if task_id in self.tasks:
+            task = self.tasks[task_id]
+            task.status = "completed"
+            task.end_time = time.time()
+            task.duration = task.end_time - (task.start_time or task.end_time)
+            if details:
+                task.details = details
+            if files_changed:
+                task.files_changed = files_changed
+            self._update_progress_file()
+            self.console.print(f"[green]✅[/green] Completed: {task.name}")
+            if self.current_task == task_id:
+                self.current_task = None
+
+    def fail_task(
+        self,
+        task_id: str,
+        error_message: str,
+        details: str | None = None,
+    ) -> None:
+        if task_id in self.tasks:
+            task = self.tasks[task_id]
+            task.status = "failed"
+            task.end_time = time.time()
+            task.duration = task.end_time - (task.start_time or task.end_time)
+            task.error_message = error_message
+            if details:
+                task.details = details
+            self._update_progress_file()
+            self.console.print(f"[red]❌[/red] Failed: {task.name} - {error_message}")
+            if self.current_task == task_id:
+                self.current_task = None
+
+    def skip_task(self, task_id: str, reason: str) -> None:
+        if task_id in self.tasks:
+            task = self.tasks[task_id]
+            task.status = "skipped"
+            task.end_time = time.time()
+            task.details = f"Skipped: {reason}"
+            self._update_progress_file()
+            self.console.print(f"[blue]⏩[/blue] Skipped: {task.name} - {reason}")
+            if self.current_task == task_id:
+                self.current_task = None
+
+    def _update_progress_file(self) -> None:
+        try:
+            content = self._generate_markdown_content()
+            self.progress_file.write_text(content, encoding="utf-8")
+        except OSError as e:
+            self.console.print(
+                f"[yellow]Warning: Failed to update progress file: {e}[/yellow]"
+            )
+
+    def _generate_header_section(self) -> str:
+        from datetime import datetime
+
+        completed_tasks = sum(
+            1 for task in self.tasks.values() if task.status == "completed"
+        )
+        total_tasks = len(self.tasks)
+        overall_status = "In Progress"
+        if completed_tasks == total_tasks and total_tasks > 0:
+            overall_status = "Completed"
+        elif any(task.status == "failed" for task in self.tasks.values()):
+            overall_status = "Failed"
+        start_datetime = datetime.fromtimestamp(self.start_time)
+
+        return f"""# Crackerjack Session Progress: {self.session_id}
+**Session ID**: {self.session_id}
+**Started**: {start_datetime.strftime("%Y-%m-%d %H:%M:%S")}
+**Status**: {overall_status}
+**Progress**: {completed_tasks}/{total_tasks} tasks completed
+
+- **Working Directory**: {self.metadata.get("working_dir", Path.cwd())}
+- **Python Version**: {self.metadata.get("python_version", "Unknown")}
+- **Crackerjack Version**: {self.metadata.get("crackerjack_version", "Unknown")}
+- **CLI Options**: {self.metadata.get("cli_options", "Unknown")}
+
+"""
+
+    def _generate_task_overview_section(self) -> str:
+        content = """## Task Progress Overview
+| Task | Status | Duration | Details |
+|------|--------|----------|---------|
+"""
+
+        for task in self.tasks.values():
+            status_emoji = {
+                "pending": "⏸️",
+                "in_progress": "⏳",
+                "completed": "✅",
+                "failed": "❌",
+                "skipped": "⏩",
+            }.get(task.status, "❓")
+
+            duration_str = f"{task.duration:.2f}s" if task.duration else "N/A"
+            details_str = (
+                task.details[:50] + "..."
+                if task.details and len(task.details) > 50
+                else (task.details or "")
+            )
+
+            content += f"| {task.name} | {status_emoji} {task.status} | {duration_str} | {details_str} |\n"
+
+        return content + "\n"
+
+    def _generate_task_details_section(self) -> str:
+        content = "## Detailed Task Log\n\n"
+        for task in self.tasks.values():
+            content += self._format_task_detail(task)
+        return content
+
+    def _format_task_detail(self, task: TaskStatus) -> str:
+        from datetime import datetime
+
+        if task.status == "completed":
+            return self._format_completed_task(task, datetime)
+        elif task.status == "in_progress":
+            return self._format_in_progress_task(task, datetime)
+        elif task.status == "failed":
+            return self._format_failed_task(task, datetime)
+        elif task.status == "skipped":
+            return self._format_skipped_task(task)
+        return ""
+
+    def _format_completed_task(self, task: TaskStatus, datetime: t.Any) -> str:
+        start_time = (
+            datetime.fromtimestamp(task.start_time) if task.start_time else "Unknown"
+        )
+        end_time = datetime.fromtimestamp(task.end_time) if task.end_time else "Unknown"
+        files_list = ", ".join(task.files_changed) if task.files_changed else "None"
+        return f"""### ✅ {task.name} - COMPLETED
+- **Started**: {start_time}
+- **Completed**: {end_time}
+- **Duration**: {task.duration:.2f}s
+- **Files Changed**: {files_list}
+- **Details**: {task.details or "N/A"}
+
+"""
+
+    def _format_in_progress_task(self, task: TaskStatus, datetime: t.Any) -> str:
+        start_time = (
+            datetime.fromtimestamp(task.start_time) if task.start_time else "Unknown"
+        )
+        return f"""### ⏳ {task.name} - IN PROGRESS
+- **Started**: {start_time}
+- **Current Status**: {task.details or "Processing..."}
+
+"""
+
+    def _format_failed_task(self, task: TaskStatus, datetime: t.Any) -> str:
+        start_time = (
+            datetime.fromtimestamp(task.start_time) if task.start_time else "Unknown"
+        )
+        fail_time = (
+            datetime.fromtimestamp(task.end_time) if task.end_time else "Unknown"
+        )
+        return f"""### ❌ {task.name} - FAILED
+- **Started**: {start_time}
+- **Failed**: {fail_time}
+- **Error**: {task.error_message or "Unknown error"}
+- **Recovery Suggestions**: Check error details and retry the failed operation
+
+"""
+
+    def _format_skipped_task(self, task: TaskStatus) -> str:
+        return f"""### ⏩ {task.name} - SKIPPED
+- **Reason**: {task.details or "No reason provided"}
+
+"""
+
+    def _generate_footer_section(self) -> str:
+        content = f"""## Session Recovery Information
+If this session was interrupted, you can resume from where you left off:
+
+```bash
+python -m crackerjack --resume-from {self.progress_file.name}
+```
+
+"""
+
+        all_files: set[str] = set()
+        for task in self.tasks.values():
+            if task.files_changed:
+                all_files.update(task.files_changed)
+
+        if all_files:
+            for file_path in sorted(all_files):
+                content += f"- {file_path}\n"
+        else:
+            content += "- No files modified yet\n"
+
+        content += "\n## Next Steps\n\n"
+
+        pending_tasks = [
+            task for task in self.tasks.values() if task.status == "pending"
+        ]
+        in_progress_tasks = [
+            task for task in self.tasks.values() if task.status == "in_progress"
+        ]
+        failed_tasks = [task for task in self.tasks.values() if task.status == "failed"]
+
+        if failed_tasks:
+            content += "⚠️ Address failed tasks:\n"
+            for task in failed_tasks:
+                content += f"- Fix {task.name}: {task.error_message}\n"
+        elif in_progress_tasks:
+            content += "🔄 Currently working on:\n"
+            for task in in_progress_tasks:
+                content += f"- {task.name}\n"
+        elif pending_tasks:
+            content += "📋 Next tasks to complete:\n"
+            for task in pending_tasks:
+                content += f"- {task.name}\n"
+        else:
+            content += "🎉 All tasks completed successfully!\n"
+
+        return content
+
+    def _generate_markdown_content(self) -> str:
+        return (
+            self._generate_header_section()
+            + self._generate_task_overview_section()
+            + self._generate_task_details_section()
+            + self._generate_footer_section()
+        )
+
+    @classmethod
+    def create_session(
+        cls,
+        console: Console,
+        session_id: str | None = None,
+        progress_file: Path | None = None,
+        metadata: dict[str, t.Any] | None = None,
+    ) -> "SessionTracker":
+        import uuid
+
+        if session_id is None:
+            session_id = str(uuid.uuid4())[:8]
+
+        if progress_file is None:
+            timestamp = time.strftime("%Y%m%d-%H%M%S")
+            progress_file = Path(f"SESSION-PROGRESS-{timestamp}.md")
+
+        tracker = cls(
+            console=console,
+            session_id=session_id,
+            start_time=time.time(),
+            progress_file=progress_file,
+            metadata=metadata or {},
+        )
+
+        tracker._update_progress_file()
+        console.print(f"[green]📋[/green] Session tracking started: {progress_file}")
+        return tracker
+
+    @classmethod
+    def find_recent_progress_files(cls, directory: Path = Path.cwd()) -> list[Path]:
+        progress_files: list[Path] = []
+        for file_path in directory.glob("SESSION-PROGRESS-*.md"):
+            try:
+                if file_path.is_file():
+                    progress_files.append(file_path)
+            except (OSError, PermissionError):
+                continue
+
+        return sorted(progress_files, key=lambda p: p.stat().st_mtime, reverse=True)
+
+    @classmethod
+    def is_session_incomplete(cls, progress_file: Path) -> bool:
+        if not progress_file.exists():
+            return False
+        try:
+            content = progress_file.read_text(encoding="utf-8")
+            has_in_progress = "⏳" in content or "in_progress" in content
+            has_failed = "❌" in content or "failed" in content
+            has_pending = "⏸️" in content or "pending" in content
+            stat = progress_file.stat()
+            age_hours = (time.time() - stat.st_mtime) / 3600
+            is_recent = age_hours < 24
+
+            return (has_in_progress or has_failed or has_pending) and is_recent
+        except (OSError, UnicodeDecodeError):
+            return False
+
+    @classmethod
+    def find_incomplete_session(cls, directory: Path = Path.cwd()) -> Path | None:
+        recent_files = cls.find_recent_progress_files(directory)
+        for progress_file in recent_files:
+            if cls.is_session_incomplete(progress_file):
+                return progress_file
+
+        return None
+
+    @classmethod
+    def auto_detect_session(
+        cls, console: Console, directory: Path = Path.cwd()
+    ) -> "SessionTracker | None":
+        incomplete_session = cls.find_incomplete_session(directory)
+        if incomplete_session:
+            return cls._handle_incomplete_session(console, incomplete_session)
+        return None
+
+    @classmethod
+    def _handle_incomplete_session(
+        cls, console: Console, incomplete_session: Path
+    ) -> "SessionTracker | None":
+        console.print(
+            f"[yellow]📋[/yellow] Found incomplete session: {incomplete_session.name}"
+        )
+        try:
+            content = incomplete_session.read_text(encoding="utf-8")
+            session_info = cls._parse_session_info(content)
+            cls._display_session_info(console, session_info)
+            return cls._prompt_resume_session(console, incomplete_session)
+        except Exception as e:
+            console.print(f"[yellow]⚠️[/yellow] Could not parse session file: {e}")
+            return None
+
+    @classmethod
+    def _parse_session_info(cls, content: str) -> dict[str, str | list[str] | None]:
+        import re
+
+        session_match = re.search(r"Session ID\*\*:\s*(.+)", content)
+        session_id: str = session_match.group(1).strip() if session_match else "unknown"
+        progress_match = re.search(r"Progress\*\*:\s*(\d+)/(\d+)", content)
+        progress_info: str | None = None
+        if progress_match:
+            completed = progress_match.group(1)
+            total = progress_match.group(2)
+            progress_info = f"{completed}/{total} tasks completed"
+        failed_tasks: list[str] = []
+        for line in content.split("\n"):
+            if "❌" in line and "- FAILED" in line:
+                task_match = re.search(r"### ❌ (.+?) - FAILED", line)
+                if task_match:
+                    task_name: str = task_match.group(1)
+                    failed_tasks.append(task_name)
+
+        return {
+            "session_id": session_id,
+            "progress_info": progress_info,
+            "failed_tasks": failed_tasks,
+        }
+
+    @classmethod
+    def _display_session_info(
+        cls, console: Console, session_info: dict[str, str | list[str] | None]
+    ) -> None:
+        console.print(f"[cyan]   Session ID:[/cyan] {session_info['session_id']}")
+        if session_info["progress_info"]:
+            console.print(f"[cyan]   Progress:[/cyan] {session_info['progress_info']}")
+        if session_info["failed_tasks"]:
+            console.print(
+                f"[red]   Failed tasks:[/red] {', '.join(session_info['failed_tasks'])}"
+            )
+
+    @classmethod
+    def _prompt_resume_session(
+        cls, console: Console, incomplete_session: Path
+    ) -> "SessionTracker | None":
+        try:
+            import sys
+
+            console.print("[yellow]❓[/yellow] Resume this session? [y/N]: ", end="")
+            sys.stdout.flush()
+            response = input().strip().lower()
+            if response in ("y", "yes"):
+                return cls.resume_session(console, incomplete_session)
+            else:
+                console.print("[blue]ℹ️[/blue] Starting new session instead")
+                return None
+        except (KeyboardInterrupt, EOFError):
+            console.print("\n[blue]ℹ️[/blue] Starting new session instead")
+            return None
+
+    @classmethod
+    def resume_session(cls, console: Console, progress_file: Path) -> "SessionTracker":
+        if not progress_file.exists():
+            raise FileNotFoundError(f"Progress file not found: {progress_file}")
+        try:
+            content = progress_file.read_text(encoding="utf-8")
+            session_id = "resumed"
+            import re
+
+            session_match = re.search(r"Session ID\*\*:\s*(.+)", content)
+            if session_match:
+                session_id = session_match.group(1).strip()
+            tracker = cls(
+                console=console,
+                session_id=session_id,
+                start_time=time.time(),
+                progress_file=progress_file,
+                metadata={},
+            )
+            console.print(f"[green]🔄[/green] Resumed session from: {progress_file}")
+            return tracker
+        except Exception as e:
+            raise RuntimeError(f"Failed to resume session: {e}") from e
+
+
 config_files = (
     ".gitignore",
     ".pre-commit-config.yaml",
@@ -44,6 +501,11 @@ config_files = (
     ".pre-commit-config-fast.yaml",
     ".libcst.codemod.yaml",
 )
+
+documentation_files = (
+    "CLAUDE.md",
+    "RULES.md",
+)
 default_python_version = "3.13"
 
 
@@ -61,6 +523,9 @@ class OptionsProtocol(t.Protocol):
     no_config_updates: bool
     verbose: bool
     update_precommit: bool
+    update_docs: bool
+    force_update_docs: bool
+    compress_docs: bool
     clean: bool
     test: bool
     benchmark: bool
@@ -76,6 +541,9 @@ class OptionsProtocol(t.Protocol):
     skip_hooks: bool = False
     comprehensive: bool = False
     async_mode: bool = False
+    track_progress: bool = False
+    resume_from: str | None = None
+    progress_file: str | None = None
 
 
 class CodeCleaner(BaseModel, arbitrary_types_allowed=True):
@@ -1216,6 +1684,363 @@ class ConfigManager(BaseModel, arbitrary_types_allowed=True):
         if configs_to_add:
             self.execute_command(["git", "add"] + configs_to_add)
 
+    def copy_documentation_templates(
+        self, force_update: bool = False, compress_docs: bool = False
+    ) -> None:
+        docs_to_add: list[str] = []
+        for doc_file in documentation_files:
+            if self._should_process_doc_file(doc_file):
+                self._process_single_doc_file(
+                    doc_file, force_update, compress_docs, docs_to_add
+                )
+
+        if docs_to_add:
+            self.execute_command(["git", "add"] + docs_to_add)
+
+    def _should_process_doc_file(self, doc_file: str) -> bool:
+        doc_path = self.our_path / doc_file
+        if not doc_path.exists():
+            return False
+        if self.pkg_path.stem == "crackerjack":
+            return False
+        return True
+
+    def _process_single_doc_file(
+        self,
+        doc_file: str,
+        force_update: bool,
+        compress_docs: bool,
+        docs_to_add: list[str],
+    ) -> None:
+        doc_path = self.our_path / doc_file
+        pkg_doc_path = self.pkg_path / doc_file
+        should_update = force_update or not pkg_doc_path.exists()
+
+        if should_update:
+            pkg_doc_path.touch()
+            content = doc_path.read_text(encoding="utf-8")
+
+            auto_compress = self._should_compress_doc(doc_file, compress_docs)
+            updated_content = self._customize_documentation_content(
+                content, doc_file, auto_compress
+            )
+            pkg_doc_path.write_text(updated_content, encoding="utf-8")
+            docs_to_add.append(doc_file)
+
+            self._print_doc_update_message(doc_file, auto_compress)
+
+    def _should_compress_doc(self, doc_file: str, compress_docs: bool) -> bool:
+        return compress_docs or (
+            self.pkg_path.stem != "crackerjack" and doc_file == "CLAUDE.md"
+        )
+
+    def _print_doc_update_message(self, doc_file: str, auto_compress: bool) -> None:
+        compression_note = (
+            " (compressed for Claude Code)"
+            if auto_compress and doc_file == "CLAUDE.md"
+            else ""
+        )
+        self.console.print(
+            f"[green]📋[/green] Updated {doc_file} with latest Crackerjack quality standards{compression_note}"
+        )
+
+    def _customize_documentation_content(
+        self, content: str, filename: str, compress: bool = False
+    ) -> str:
+        if filename == "CLAUDE.md":
+            return self._customize_claude_md(content, compress)
+        elif filename == "RULES.md":
+            return self._customize_rules_md(content)
+        return content
+
+    def _compress_claude_md(self, content: str, target_size: int = 30000) -> str:
+        content.split("\n")
+        current_size = len(content)
+        if current_size <= target_size:
+            return content
+        essential_sections = [
+            "# ",
+            "## Project Overview",
+            "## Key Commands",
+            "## Development Guidelines",
+            "## Code Quality Compliance",
+            "### Refurb Standards",
+            "### Bandit Security Standards",
+            "### Pyright Type Safety Standards",
+            "## AI Code Generation Best Practices",
+            "## Task Completion Requirements",
+        ]
+        compression_strategies = [
+            self._remove_redundant_examples,
+            self._compress_command_examples,
+            self._remove_verbose_sections,
+            self._compress_repeated_patterns,
+            self._summarize_long_sections,
+        ]
+        compressed_content = content
+        for strategy in compression_strategies:
+            compressed_content = strategy(compressed_content)
+            if len(compressed_content) <= target_size:
+                break
+        if len(compressed_content) > target_size:
+            compressed_content = self._extract_essential_sections(
+                compressed_content, essential_sections, target_size
+            )
+
+        return self._add_compression_notice(compressed_content)
+
+    def _remove_redundant_examples(self, content: str) -> str:
+        lines = content.split("\n")
+        result = []
+        in_example_block = False
+        example_count = 0
+        max_examples_per_section = 2
+        for line in lines:
+            if line.strip().startswith("```"):
+                if not in_example_block:
+                    example_count += 1
+                    if example_count <= max_examples_per_section:
+                        result.append(line)
+                        in_example_block = True
+                    else:
+                        in_example_block = "skip"
+                else:
+                    if in_example_block != "skip":
+                        result.append(line)
+                    in_example_block = False
+            elif in_example_block == "skip":
+                continue
+            elif line.startswith(("## ", "### ")):
+                example_count = 0
+                result.append(line)
+            else:
+                result.append(line)
+
+        return "\n".join(result)
+
+    def _compress_command_examples(self, content: str) -> str:
+        import re
+
+        content = re.sub(
+            r"```bash\n((?:[^`]+\n){3,})```",
+            lambda m: "```bash\n"
+            + "\n".join(m.group(1).split("\n")[:3])
+            + "\n# ... (additional commands available)\n```",
+            content,
+            flags=re.MULTILINE,
+        )
+
+        return content
+
+    def _remove_verbose_sections(self, content: str) -> str:
+        sections_to_compress = [
+            "## Recent Bug Fixes and Improvements",
+            "## Development Memories",
+            "## Self-Maintenance Protocol for AI Assistants",
+            "## Pre-commit Hook Maintenance",
+        ]
+        lines = content.split("\n")
+        result = []
+        skip_section = False
+        for line in lines:
+            if any(line.startswith(section) for section in sections_to_compress):
+                skip_section = True
+                result.extend(
+                    (line, "*[Detailed information available in full CLAUDE.md]*")
+                )
+                result.append("")
+            elif line.startswith("## ") and skip_section:
+                skip_section = False
+                result.append(line)
+            elif not skip_section:
+                result.append(line)
+
+        return "\n".join(result)
+
+    def _compress_repeated_patterns(self, content: str) -> str:
+        import re
+
+        content = re.sub(r"\n{3,}", "\n\n", content)
+        content = re.sub(
+            r"(\*\*[A-Z][^*]+:\*\*[^\n]+\n){3,}",
+            lambda m: m.group(0)[:200]
+            + "...\n*[Additional patterns available in full documentation]*\n",
+            content,
+        )
+
+        return content
+
+    def _summarize_long_sections(self, content: str) -> str:
+        lines = content.split("\n")
+        result = []
+        current_section = []
+        section_header = ""
+        for line in lines:
+            if line.startswith(("### ", "## ")):
+                if current_section and len("\n".join(current_section)) > 1000:
+                    summary = self._create_section_summary(
+                        section_header, current_section
+                    )
+                    result.extend(summary)
+                else:
+                    result.extend(current_section)
+                current_section = [line]
+                section_header = line
+            else:
+                current_section.append(line)
+        if current_section:
+            if len("\n".join(current_section)) > 1000:
+                summary = self._create_section_summary(section_header, current_section)
+                result.extend(summary)
+            else:
+                result.extend(current_section)
+
+        return "\n".join(result)
+
+    def _create_section_summary(
+        self, header: str, section_lines: list[str]
+    ) -> list[str]:
+        summary = [header, ""]
+
+        key_points = []
+        for line in section_lines[2:]:
+            if line.strip().startswith(("- ", "* ", "1. ", "2. ")):
+                key_points.append(line)
+            elif line.strip().startswith("**") and ":" in line:
+                key_points.append(line)
+
+            if len(key_points) >= 5:
+                break
+
+        if key_points:
+            summary.extend(key_points[:5])
+            summary.append("*[Complete details available in full CLAUDE.md]*")
+        else:
+            content_preview = " ".join(
+                line.strip()
+                for line in section_lines[2:10]
+                if line.strip() and not line.startswith("#")
+            )[:200]
+            summary.extend(
+                (
+                    f"{content_preview}...",
+                    "*[Full section available in complete documentation]*",
+                )
+            )
+
+        summary.append("")
+        return summary
+
+    def _extract_essential_sections(
+        self, content: str, essential_sections: list[str], target_size: int
+    ) -> str:
+        lines = content.split("\n")
+        result = []
+        current_section = []
+        keep_section = False
+
+        for line in lines:
+            new_section_started = self._process_line_for_section(
+                line, essential_sections, current_section, keep_section, result
+            )
+            if new_section_started is not None:
+                current_section, keep_section = new_section_started
+            else:
+                current_section.append(line)
+
+            if self._should_stop_extraction(result, target_size):
+                break
+
+        self._finalize_extraction(current_section, keep_section, result, target_size)
+        return "\n".join(result)
+
+    def _process_line_for_section(
+        self,
+        line: str,
+        essential_sections: list[str],
+        current_section: list[str],
+        keep_section: bool,
+        result: list[str],
+    ) -> tuple[list[str], bool] | None:
+        if any(line.startswith(section) for section in essential_sections):
+            if current_section and keep_section:
+                result.extend(current_section)
+            return ([line], True)
+        elif line.startswith(("## ", "### ")):
+            if current_section and keep_section:
+                result.extend(current_section)
+            return ([line], False)
+        return None
+
+    def _should_stop_extraction(self, result: list[str], target_size: int) -> bool:
+        return len("\n".join(result)) > target_size
+
+    def _finalize_extraction(
+        self,
+        current_section: list[str],
+        keep_section: bool,
+        result: list[str],
+        target_size: int,
+    ) -> None:
+        if current_section and keep_section and len("\n".join(result)) < target_size:
+            result.extend(current_section)
+
+    def _add_compression_notice(self, content: str) -> str:
+        notice = """
+*Note: This CLAUDE.md has been automatically compressed by Crackerjack to optimize for Claude Code usage.
+Complete documentation is available in the source repository.*
+
+"""
+
+        lines = content.split("\n")
+        if len(lines) > 5:
+            lines.insert(5, notice)
+
+        return "\n".join(lines)
+
+    def _customize_claude_md(self, content: str, compress: bool = False) -> str:
+        project_name = self.pkg_name
+        content = content.replace("crackerjack", project_name).replace(
+            "Crackerjack", project_name.title()
+        )
+        header = f"""# {project_name.upper()}.md
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+*This file was automatically generated by Crackerjack and contains the latest Python quality standards.*
+
+{project_name.title()} is a Python project that follows modern development practices and maintains high code quality standards using automated tools and best practices.
+
+"""
+
+        lines = content.split("\n")
+        start_idx = 0
+        for i, line in enumerate(lines):
+            if line.startswith(("## Development Guidelines", "## Code Quality")):
+                start_idx = i
+                break
+
+        if start_idx > 0:
+            relevant_content = "\n".join(lines[start_idx:])
+            full_content = header + relevant_content
+        else:
+            full_content = header + content
+
+        if compress:
+            return self._compress_claude_md(full_content)
+        return full_content
+
+    def _customize_rules_md(self, content: str) -> str:
+        project_name = self.pkg_name
+        content = content.replace("crackerjack", project_name).replace(
+            "Crackerjack", project_name.title()
+        )
+        header = f"""# {project_name.title()} Style Rules
+*This file was automatically generated by Crackerjack and contains the latest Python quality standards.*
+
+"""
+
+        return header + content
+
     def execute_command(
         self, cmd: list[str], **kwargs: t.Any
     ) -> subprocess.CompletedProcess[str]:
@@ -1307,13 +2132,22 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
                 "[bold bright_blue]⚡ INIT[/bold bright_blue] [bold bright_white]First-time project setup[/bold bright_white]"
             )
             self.console.print("─" * 80 + "\n")
-            self.execute_command(["uv", "tool", "install", "keyring"])
+            if self.options and getattr(self.options, "ai_agent", False):
+                import subprocess
+
+                self.execute_command(
+                    ["uv", "tool", "install", "keyring"],
+                    capture_output=True,
+                    stderr=subprocess.DEVNULL,
+                )
+            else:
+                self.execute_command(["uv", "tool", "install", "keyring"])
             self.execute_command(["git", "init"])
             self.execute_command(["git", "branch", "-m", "main"])
             self.execute_command(["git", "add", "pyproject.toml", "uv.lock"])
             self.execute_command(["git", "config", "advice.addIgnoredFile", "false"])
             install_cmd = ["uv", "run", "pre-commit", "install"]
-            if hasattr(self, "options") and getattr(self.options, "ai_agent", False):
+            if self.options and getattr(self.options, "ai_agent", False):
                 install_cmd.extend(["-c", ".pre-commit-config-ai.yaml"])
             else:
                 install_cmd.extend(["-c", ".pre-commit-config-fast.yaml"])
@@ -1390,7 +2224,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
         result = self.execute_command(cmd, capture_output=True, text=True)
         total_duration = time.time() - start_time
         hook_results = self._parse_hook_output(result.stdout, result.stderr)
-        if hasattr(self, "options") and getattr(self.options, "ai_agent", False):
+        if self.options and getattr(self.options, "ai_agent", False):
             self._generate_hooks_analysis(hook_results, total_duration)
             self._generate_quality_metrics()
             self._generate_project_structure_analysis()
@@ -1512,7 +2346,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
         return suggestions
 
     def _generate_quality_metrics(self) -> None:
-        if not (hasattr(self, "options") and getattr(self.options, "ai_agent", False)):
+        if not (self.options and getattr(self.options, "ai_agent", False)):
             return
         metrics = {
             "project_info": {
@@ -1687,7 +2521,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
         return recommendations
 
     def _generate_project_structure_analysis(self) -> None:
-        if not (hasattr(self, "options") and getattr(self.options, "ai_agent", False)):
+        if not (self.options and getattr(self.options, "ai_agent", False)):
             return
         structure = {
             "project_overview": {
@@ -1711,7 +2545,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
         )
 
     def _generate_error_context_analysis(self) -> None:
-        if not (hasattr(self, "options") and getattr(self.options, "ai_agent", False)):
+        if not (self.options and getattr(self.options, "ai_agent", False)):
             return
         context = {
             "analysis_info": {
@@ -1732,7 +2566,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
         )
 
     def _generate_ai_agent_summary(self) -> None:
-        if not (hasattr(self, "options") and getattr(self.options, "ai_agent", False)):
+        if not (self.options and getattr(self.options, "ai_agent", False)):
             return
         summary = {
             "analysis_summary": {
@@ -2012,7 +2846,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
             raise SystemExit(1)
         else:
             self.console.print(
-                "\n[bold bright_green]✅ Pre-commit passed all checks![/bold bright_green]"
+                "\n[bold bright_green]🏆 Pre-commit passed all checks![/bold bright_green]"
             )
 
     async def run_pre_commit_with_analysis_async(self) -> list[HookResult]:
@@ -2058,7 +2892,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
             raise SystemExit(1)
         else:
             self.console.print(
-                "\n[bold bright_green]✅ Pre-commit passed all checks![/bold bright_green]"
+                "\n[bold bright_green]🏆 Pre-commit passed all checks![/bold bright_green]"
             )
         self._generate_analysis_files(hook_results)
 
@@ -2116,6 +2950,26 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
                 f"[yellow]Warning: Failed to generate AI summary: {e}[/yellow]"
             )
 
+    def update_precommit_hooks(self) -> None:
+        try:
+            result = self.execute_command(
+                ["uv", "run", "pre-commit", "autoupdate"],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                self.console.print(
+                    "[green]✅ Pre-commit hooks updated successfully[/green]"
+                )
+                if result.stdout.strip():
+                    self.console.print(f"[dim]{result.stdout}[/dim]")
+            else:
+                self.console.print(
+                    f"[red]❌ Failed to update pre-commit hooks: {result.stderr}[/red]"
+                )
+        except Exception as e:
+            self.console.print(f"[red]❌ Error updating pre-commit hooks: {e}[/red]")
+
 
 class Crackerjack(BaseModel, arbitrary_types_allowed=True):
     our_path: Path = Path(__file__).parent
@@ -2128,6 +2982,8 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
     code_cleaner: CodeCleaner | None = None
     config_manager: ConfigManager | None = None
     project_manager: ProjectManager | None = None
+    session_tracker: SessionTracker | None = None
+    options: t.Any = None
     _file_cache: dict[str, list[Path]] = {}
     _file_cache_with_mtime: dict[str, tuple[float, list[Path]]] = {}
     _state_file: Path = Path(".crackerjack-state")
@@ -2255,13 +3111,6 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
                     "\n\n[bold red]❌ UV sync failed. Is UV installed? Run `pipx install uv` and try again.[/bold red]\n\n"
                 )
 
-    def _update_precommit(self, options: t.Any) -> None:
-        if self.pkg_path.stem == "crackerjack" and options.update_precommit:
-            update_cmd = ["uv", "run", "pre-commit", "autoupdate"]
-            if options.ai_agent:
-                update_cmd.extend(["-c", ".pre-commit-config-ai.yaml"])
-            self.execute_command(update_cmd)
-
     def _clean_project(self, options: t.Any) -> None:
         assert self.code_cleaner is not None
         if options.clean:
@@ -2529,7 +3378,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
 
     def _handle_test_success(self, options: t.Any) -> None:
         self.console.print(
-            "\n\n[bold bright_green]✅ Tests passed successfully![/bold bright_green]\n"
+            "\n\n[bold bright_green]🏆 Tests passed successfully![/bold bright_green]\n"
         )
         self._print_ai_agent_files(options)
 
@@ -2598,6 +3447,121 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
                 self._mark_version_bumped(version_type)
                 break
 
+    def _validate_authentication_setup(self) -> None:
+        import os
+        import shutil
+
+        keyring_provider = self._get_keyring_provider()
+        has_publish_token = bool(os.environ.get("UV_PUBLISH_TOKEN"))
+        has_keyring = shutil.which("keyring") is not None
+        self.console.print("[dim]🔐 Validating authentication setup...[/dim]")
+        if has_publish_token:
+            self._handle_publish_token_found()
+            return
+        if keyring_provider == "subprocess" and has_keyring:
+            self._handle_keyring_validation()
+            return
+        if keyring_provider == "subprocess" and not has_keyring:
+            self._handle_missing_keyring()
+        if not keyring_provider:
+            self._handle_no_keyring_provider()
+
+    def _handle_publish_token_found(self) -> None:
+        self.console.print(
+            "[dim]  ✅ UV_PUBLISH_TOKEN environment variable found[/dim]"
+        )
+
+    def _handle_keyring_validation(self) -> None:
+        self.console.print(
+            "[dim]  ✅ Keyring provider configured and keyring executable found[/dim]"
+        )
+        try:
+            result = self.execute_command(
+                ["keyring", "get", "https://upload.pypi.org/legacy/", "__token__"],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                self.console.print("[dim]  ✅ PyPI token found in keyring[/dim]")
+            else:
+                self.console.print(
+                    "[yellow]  ⚠️  No PyPI token found in keyring - will prompt during publish[/yellow]"
+                )
+        except Exception:
+            self.console.print(
+                "[yellow]  ⚠️  Could not check keyring - will attempt publish anyway[/yellow]"
+            )
+
+    def _handle_missing_keyring(self) -> None:
+        if not (self.options and getattr(self.options, "ai_agent", False)):
+            self.console.print(
+                "[yellow]  ⚠️  Keyring provider set to 'subprocess' but keyring executable not found[/yellow]"
+            )
+            self.console.print(
+                "[yellow]      Install keyring: uv tool install keyring[/yellow]"
+            )
+
+    def _handle_no_keyring_provider(self) -> None:
+        if not (self.options and getattr(self.options, "ai_agent", False)):
+            self.console.print(
+                "[yellow]  ⚠️  No keyring provider configured and no UV_PUBLISH_TOKEN set[/yellow]"
+            )
+
+    def _get_keyring_provider(self) -> str | None:
+        import os
+        import tomllib
+        from pathlib import Path
+
+        env_provider = os.environ.get("UV_KEYRING_PROVIDER")
+        if env_provider:
+            return env_provider
+        for config_file in ("pyproject.toml", "uv.toml"):
+            config_path = Path(config_file)
+            if config_path.exists():
+                try:
+                    with config_path.open("rb") as f:
+                        config = tomllib.load(f)
+                    return config.get("tool", {}).get("uv", {}).get("keyring-provider")
+                except Exception:
+                    continue
+
+        return None
+
+    def _build_publish_command(self) -> list[str]:
+        import os
+
+        cmd = ["uv", "publish"]
+        publish_token = os.environ.get("UV_PUBLISH_TOKEN")
+        if publish_token:
+            cmd.extend(["--token", publish_token])
+        keyring_provider = self._get_keyring_provider()
+        if keyring_provider:
+            cmd.extend(["--keyring-provider", keyring_provider])
+
+        return cmd
+
+    def _display_authentication_help(self) -> None:
+        self.console.print(
+            "\n[bold bright_red]❌ Publish failed. Run crackerjack again to retry publishing without re-bumping version.[/bold bright_red]"
+        )
+        if not (self.options and getattr(self.options, "ai_agent", False)):
+            self.console.print("\n[bold yellow]🔐 Authentication Help:[/bold yellow]")
+            self.console.print("  [dim]To fix authentication issues, you can:[/dim]")
+            self.console.print(
+                "  [dim]1. Set PyPI token: export UV_PUBLISH_TOKEN=pypi-your-token-here[/dim]"
+            )
+            self.console.print(
+                "  [dim]2. Install keyring: uv tool install keyring[/dim]"
+            )
+            self.console.print(
+                "  [dim]3. Store token in keyring: keyring set https://upload.pypi.org/legacy/ __token__[/dim]"
+            )
+            self.console.print(
+                "  [dim]4. Ensure keyring-provider is set in pyproject.toml:[/dim]"
+            )
+            self.console.print("  [dim]     [tool.uv][/dim]")
+            self.console.print('  [dim]     keyring-provider = "subprocess"[/dim]')
+
     def _publish_project(self, options: OptionsProtocol) -> None:
         if options.publish:
             self.console.print("\n" + "-" * 80)
@@ -2616,18 +3580,169 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
                 )
                 raise SystemExit(1)
             try:
-                self.execute_command(["uv", "publish"])
+                self._validate_authentication_setup()
+                publish_cmd = self._build_publish_command()
+                self.execute_command(publish_cmd)
                 self._mark_publish_completed()
                 self._clear_state()
                 self.console.print(
-                    "\n[bold bright_green]✅ Package published successfully![/bold bright_green]"
+                    "\n[bold bright_green]🏆 Package published successfully![/bold bright_green]"
                 )
             except SystemExit:
-                self.console.print(
-                    "\n[bold bright_red]❌ Publish failed. Run crackerjack again to retry publishing without re-bumping version.[/bold bright_red]"
-                )
+                self._display_authentication_help()
                 raise
 
+    def _analyze_git_changes(self) -> dict[str, t.Any]:
+        diff_result = self._get_git_diff_output()
+        changes = self._parse_git_diff_output(diff_result)
+        changes["stats"] = self._get_git_stats()
+        return changes
+
+    def _get_git_diff_output(self) -> t.Any:
+        diff_cmd = ["git", "diff", "--cached", "--name-status"]
+        diff_result = self.execute_command(diff_cmd, capture_output=True, text=True)
+        if not diff_result.stdout and diff_result.returncode == 0:
+            diff_cmd = ["git", "diff", "--name-status"]
+            diff_result = self.execute_command(diff_cmd, capture_output=True, text=True)
+        return diff_result
+
+    def _parse_git_diff_output(self, diff_result: t.Any) -> dict[str, t.Any]:
+        changes = {
+            "added": [],
+            "modified": [],
+            "deleted": [],
+            "renamed": [],
+            "total_changes": 0,
+        }
+        if diff_result.returncode == 0 and diff_result.stdout:
+            self._process_diff_lines(diff_result.stdout, changes)
+        return changes
+
+    def _process_diff_lines(self, stdout: str, changes: dict[str, t.Any]) -> None:
+        for line in stdout.strip().split("\n"):
+            if not line:
+                continue
+            self._process_single_diff_line(line, changes)
+
+    def _process_single_diff_line(self, line: str, changes: dict[str, t.Any]) -> None:
+        parts = line.split("\t")
+        if len(parts) >= 2:
+            status, filename = parts[0], parts[1]
+            self._categorize_file_change(status, filename, parts, changes)
+            changes["total_changes"] += 1
+
+    def _categorize_file_change(
+        self, status: str, filename: str, parts: list[str], changes: dict[str, t.Any]
+    ) -> None:
+        if status == "A":
+            changes["added"].append(filename)
+        elif status == "M":
+            changes["modified"].append(filename)
+        elif status == "D":
+            changes["deleted"].append(filename)
+        elif status.startswith("R"):
+            if len(parts) >= 3:
+                changes["renamed"].append((parts[1], parts[2]))
+            else:
+                changes["renamed"].append((filename, "unknown"))
+
+    def _get_git_stats(self) -> str:
+        stat_cmd = ["git", "diff", "--cached", "--stat"]
+        stat_result = self.execute_command(stat_cmd, capture_output=True, text=True)
+        if not stat_result.stdout and stat_result.returncode == 0:
+            stat_cmd = ["git", "diff", "--stat"]
+            stat_result = self.execute_command(stat_cmd, capture_output=True, text=True)
+        return stat_result.stdout if stat_result.returncode == 0 else ""
+
+    def _categorize_changes(self, changes: dict[str, t.Any]) -> dict[str, list[str]]:
+        categories = {
+            "docs": [],
+            "tests": [],
+            "config": [],
+            "core": [],
+            "ci": [],
+            "deps": [],
+        }
+        file_patterns = {
+            "docs": ["README.md", "CLAUDE.md", "RULES.md", "docs/", ".md"],
+            "tests": ["test_", "_test.py", "tests/", "conftest.py"],
+            "config": ["pyproject.toml", ".yaml", ".yml", ".json", ".gitignore"],
+            "ci": [".github/", "ci/", ".pre-commit"],
+            "deps": ["requirements", "pyproject.toml", "uv.lock"],
+        }
+        for file_list in ("added", "modified", "deleted"):
+            for filename in changes.get(file_list, []):
+                categorized = False
+                for category, patterns in file_patterns.items():
+                    if any(pattern in filename for pattern in patterns):
+                        categories[category].append(filename)
+                        categorized = True
+                        break
+                if not categorized:
+                    categories["core"].append(filename)
+
+        return categories
+
+    def _get_primary_changes(self, categories: dict[str, list[str]]) -> list[str]:
+        primary_changes = []
+        category_mapping = [
+            ("core", "core functionality"),
+            ("tests", "tests"),
+            ("docs", "documentation"),
+            ("config", "configuration"),
+            ("deps", "dependencies"),
+        ]
+        for key, label in category_mapping:
+            if categories[key]:
+                primary_changes.append(label)
+
+        return primary_changes or ["project files"]
+
+    def _determine_primary_action(self, changes: dict[str, t.Any]) -> str:
+        added_count = len(changes["added"])
+        modified_count = len(changes["modified"])
+        deleted_count = len(changes["deleted"])
+        if added_count > modified_count + deleted_count:
+            return "Add"
+        elif deleted_count > modified_count + added_count:
+            return "Remove"
+        elif changes["renamed"]:
+            return "Refactor"
+        return "Update"
+
+    def _generate_body_lines(self, changes: dict[str, t.Any]) -> list[str]:
+        body_lines = []
+        change_types = [
+            ("added", "Added"),
+            ("modified", "Modified"),
+            ("deleted", "Deleted"),
+            ("renamed", "Renamed"),
+        ]
+        for change_type, label in change_types:
+            items = changes.get(change_type, [])
+            if items:
+                count = len(items)
+                body_lines.append(f"- {label} {count} file(s)")
+                if change_type not in ("deleted", "renamed"):
+                    for file in items[:3]:
+                        body_lines.append(f"  * {file}")
+                    if count > 3:
+                        body_lines.append(f"  * ... and {count - 3} more")
+
+        return body_lines
+
+    def _generate_commit_message(self, changes: dict[str, t.Any]) -> str:
+        if changes["total_changes"] == 0:
+            return "Update project files"
+        categories = self._categorize_changes(changes)
+        primary_changes = self._get_primary_changes(categories)
+        primary_action = self._determine_primary_action(changes)
+        commit_subject = f"{primary_action} {' and '.join(primary_changes[:2])}"
+        body_lines = self._generate_body_lines(changes)
+        if body_lines:
+            return f"{commit_subject}\n\n" + "\n".join(body_lines)
+        return commit_subject
+
     def _commit_and_push(self, options: OptionsProtocol) -> None:
         if options.commit:
             self.console.print("\n" + "-" * 80)
@@ -2635,12 +3750,71 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
                 "[bold bright_white]📝 COMMIT[/bold bright_white] [bold bright_white]Saving changes to git[/bold bright_white]"
             )
             self.console.print("-" * 80 + "\n")
-            commit_msg = input("\nCommit message: ")
+            changes = self._analyze_git_changes()
+            if changes["total_changes"] > 0:
+                self.console.print("[dim]🔍 Analyzing changes...[/dim]\n")
+                if changes["stats"]:
+                    self.console.print(changes["stats"])
+                suggested_msg = self._generate_commit_message(changes)
+                self.console.print(
+                    "\n[bold cyan]📋 Suggested commit message:[/bold cyan]"
+                )
+                self.console.print(f"[cyan]{suggested_msg}[/cyan]\n")
+                user_choice = (
+                    input("Use suggested message? [Y/n/e to edit]: ").strip().lower()
+                )
+                if user_choice in ("", "y"):
+                    commit_msg = suggested_msg
+                elif user_choice == "e":
+                    import os
+                    import tempfile
+
+                    with tempfile.NamedTemporaryFile(
+                        mode="w", suffix=".txt", delete=False
+                    ) as f:
+                        f.write(suggested_msg)
+                        temp_path = f.name
+                    editor = os.environ.get("EDITOR", "vi")
+                    self.execute_command([editor, temp_path])
+                    with open(temp_path) as f:
+                        commit_msg = f.read().strip()
+                    Path(temp_path).unlink()
+                else:
+                    commit_msg = input("\nEnter custom commit message: ")
+            else:
+                commit_msg = input("\nCommit message: ")
             self.execute_command(
                 ["git", "commit", "-m", commit_msg, "--no-verify", "--", "."]
             )
             self.execute_command(["git", "push", "origin", "main", "--no-verify"])
 
+    def _update_precommit(self, options: OptionsProtocol) -> None:
+        if options.update_precommit:
+            self.console.print("\n" + "-" * 80)
+            self.console.print(
+                "[bold bright_blue]🔄 UPDATE[/bold bright_blue] [bold bright_white]Updating pre-commit hooks[/bold bright_white]"
+            )
+            self.console.print("-" * 80 + "\n")
+            if self.pkg_path.stem == "crackerjack":
+                update_cmd = ["uv", "run", "pre-commit", "autoupdate"]
+                if getattr(options, "ai_agent", False):
+                    update_cmd.extend(["-c", ".pre-commit-config-ai.yaml"])
+                self.execute_command(update_cmd)
+            else:
+                self.project_manager.update_precommit_hooks()
+
+    def _update_docs(self, options: OptionsProtocol) -> None:
+        if options.update_docs or options.force_update_docs:
+            self.console.print("\n" + "-" * 80)
+            self.console.print(
+                "[bold bright_blue]📋 DOCS UPDATE[/bold bright_blue] [bold bright_white]Updating documentation with quality standards[/bold bright_white]"
+            )
+            self.console.print("-" * 80 + "\n")
+            self.config_manager.copy_documentation_templates(
+                force_update=options.force_update_docs,
+                compress_docs=options.compress_docs,
+            )
+
     def execute_command(
         self, cmd: list[str], **kwargs: t.Any
     ) -> subprocess.CompletedProcess[str]:
@@ -2712,7 +3886,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             raise SystemExit(1)
         else:
             self.console.print(
-                "\n[bold bright_green]✅ All comprehensive quality checks passed![/bold bright_green]"
+                "\n[bold bright_green]🏆 All comprehensive quality checks passed![/bold bright_green]"
             )
 
     async def _run_comprehensive_quality_checks_async(
@@ -2762,11 +3936,86 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             raise SystemExit(1)
         else:
             self.console.print(
-                "[bold bright_green]✅ All comprehensive quality checks passed![/bold bright_green]"
+                "[bold bright_green]🏆 All comprehensive quality checks passed![/bold bright_green]"
+            )
+
+    def _run_tracked_task(
+        self, task_id: str, task_name: str, task_func: t.Callable[[], None]
+    ) -> None:
+        if self.session_tracker:
+            self.session_tracker.start_task(task_id, task_name)
+        try:
+            task_func()
+            if self.session_tracker:
+                self.session_tracker.complete_task(task_id, f"{task_name} completed")
+        except Exception as e:
+            if self.session_tracker:
+                self.session_tracker.fail_task(task_id, str(e))
+            raise
+
+    def _run_pre_commit_task(self, options: OptionsProtocol) -> None:
+        if not options.skip_hooks:
+            if getattr(options, "ai_agent", False):
+                self.project_manager.run_pre_commit_with_analysis()
+            else:
+                self.project_manager.run_pre_commit()
+        else:
+            self.console.print(
+                "\n[bold bright_yellow]⏭️  Skipping pre-commit hooks...[/bold bright_yellow]\n"
             )
+            if self.session_tracker:
+                self.session_tracker.skip_task("pre_commit", "Skipped by user request")
+
+    def _initialize_session_tracking(self, options: OptionsProtocol) -> None:
+        if options.resume_from:
+            try:
+                progress_file = Path(options.resume_from)
+                self.session_tracker = SessionTracker.resume_session(
+                    console=self.console,
+                    progress_file=progress_file,
+                )
+                return
+            except Exception as e:
+                self.console.print(
+                    f"[yellow]Warning: Failed to resume from {options.resume_from}: {e}[/yellow]"
+                )
+                self.session_tracker = None
+                return
+        if options.track_progress:
+            try:
+                auto_tracker = SessionTracker.auto_detect_session(self.console)
+                if auto_tracker:
+                    self.session_tracker = auto_tracker
+                    return
+                progress_file = (
+                    Path(options.progress_file) if options.progress_file else None
+                )
+                try:
+                    from importlib.metadata import version
+
+                    crackerjack_version = version("crackerjack")
+                except (ImportError, ModuleNotFoundError):
+                    crackerjack_version = "unknown"
+                metadata = {
+                    "working_dir": str(self.pkg_path),
+                    "python_version": self.python_version,
+                    "crackerjack_version": crackerjack_version,
+                    "cli_options": str(options),
+                }
+                self.session_tracker = SessionTracker.create_session(
+                    console=self.console,
+                    progress_file=progress_file,
+                    metadata=metadata,
+                )
+            except Exception as e:
+                self.console.print(
+                    f"[yellow]Warning: Failed to initialize session tracking: {e}[/yellow]"
+                )
+                self.session_tracker = None
 
     def process(self, options: OptionsProtocol) -> None:
         assert self.project_manager is not None
+        self._initialize_session_tracking(options)
         self.console.print("\n" + "-" * 80)
         self.console.print(
             "[bold bright_cyan]⚒️ CRACKERJACKING[/bold bright_cyan] [bold bright_white]Starting workflow execution[/bold bright_white]"
@@ -2777,28 +4026,59 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             options.test = True
             options.publish = options.all
             options.commit = True
-        self._setup_package()
-        self._update_project(options)
-        self._update_precommit(options)
-        self._clean_project(options)
-        self.project_manager.options = options
+        self._run_tracked_task(
+            "setup", "Initialize project structure", self._setup_package
+        )
+        self._run_tracked_task(
+            "update_project",
+            "Update project configuration",
+            lambda: self._update_project(options),
+        )
+        self._run_tracked_task(
+            "update_precommit",
+            "Update pre-commit hooks",
+            lambda: self._update_precommit(options),
+        )
+        self._run_tracked_task(
+            "update_docs",
+            "Update documentation templates",
+            lambda: self._update_docs(options),
+        )
+        self._run_tracked_task(
+            "clean_project", "Clean project code", lambda: self._clean_project(options)
+        )
+        if self.project_manager is not None:
+            self.project_manager.options = options
         if not options.skip_hooks:
-            if getattr(options, "ai_agent", False):
-                self.project_manager.run_pre_commit_with_analysis()
-            else:
-                self.project_manager.run_pre_commit()
-        else:
-            self.console.print(
-                "\n[bold bright_yellow]⏭️  Skipping pre-commit hooks...[/bold bright_yellow]\n"
+            self._run_tracked_task(
+                "pre_commit",
+                "Run pre-commit hooks",
+                lambda: self._run_pre_commit_task(options),
             )
-        self._run_tests(options)
-        self._run_comprehensive_quality_checks(options)
-        self._bump_version(options)
-        self._commit_and_push(options)
-        self._publish_project(options)
+        else:
+            self._run_pre_commit_task(options)
+        self._run_tracked_task(
+            "run_tests", "Execute test suite", lambda: self._run_tests(options)
+        )
+        self._run_tracked_task(
+            "quality_checks",
+            "Run comprehensive quality checks",
+            lambda: self._run_comprehensive_quality_checks(options),
+        )
+        self._run_tracked_task(
+            "bump_version", "Bump version numbers", lambda: self._bump_version(options)
+        )
+        self._run_tracked_task(
+            "commit_push",
+            "Commit and push changes",
+            lambda: self._commit_and_push(options),
+        )
+        self._run_tracked_task(
+            "publish", "Publish project", lambda: self._publish_project(options)
+        )
         self.console.print("\n" + "-" * 80)
         self.console.print(
-            "[bold bright_green]✨ CRACKERJACK COMPLETE[/bold bright_green] [bold bright_white]Workflow completed successfully![/bold bright_white]"
+            "[bold bright_green]🏆 CRACKERJACK COMPLETE[/bold bright_green] [bold bright_white]Workflow completed successfully![/bold bright_white]"
         )
         self.console.print("-" * 80 + "\n")
 
@@ -2818,7 +4098,8 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
         self._update_project(options)
         self._update_precommit(options)
         await self._clean_project_async(options)
-        self.project_manager.options = options
+        if self.project_manager is not None:
+            self.project_manager.options = options
         if not options.skip_hooks:
             if getattr(options, "ai_agent", False):
                 await self.project_manager.run_pre_commit_with_analysis_async()
@@ -2835,7 +4116,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
         self._publish_project(options)
         self.console.print("\n" + "-" * 80)
         self.console.print(
-            "[bold bright_green]✨ CRACKERJACK COMPLETE[/bold bright_green] [bold bright_white]Workflow completed successfully![/bold bright_white]"
+            "[bold bright_green]🏆 CRACKERJACK COMPLETE[/bold bright_green] [bold bright_white]Workflow completed successfully![/bold bright_white]"
         )
         self.console.print("-" * 80 + "\n")