codetour-cli 0.1.0__py3-none-any.whl

codetour_cli/cli.py

@@ -0,0 +1,2087 @@
+"""
+CodeTour CLI - Command line interface for maintaining CodeTours.
+"""
+
+import sys
+import argparse
+from pathlib import Path
+from datetime import datetime, timezone
+from typing import Optional
+
+import structlog
+from git import Repo, InvalidGitRepositoryError
+
+from codetour_cli.logging.setup import configure_logging
+from codetour_cli.detection import detect_source_commit
+from codetour_cli.tour.updater import update_tour_file
+from codetour_cli.tour.schema import Tour
+from codetour_cli.discovery import discover_repository, is_tour_up_to_date, find_repo_root, find_tours_directory, scan_tours
+from codetour_cli.config import generate_config_file, load_config
+from codetour_cli.schema_models import ParsingSchema, FieldSchema
+
+log = structlog.get_logger()
+
+
+def get_jinja_env():
+    """
+    Get Jinja2 environment configured for templates.
+
+    Returns:
+        Jinja2 Environment instance
+    """
+    from jinja2 import Environment, FileSystemLoader
+
+    template_dir = Path(__file__).parent / 'templates'
+    return Environment(
+        loader=FileSystemLoader(str(template_dir)),
+        autoescape=False,  # Markdown doesn't need HTML escaping
+        trim_blocks=True,
+        lstrip_blocks=True
+    )
+
+
+def render_template(template_name: str, **context) -> str:
+    """
+    Render a Jinja2 template with the given context.
+
+    Args:
+        template_name: Name of the template file (e.g., 'review_report.md')
+        **context: Variables to pass to the template
+
+    Returns:
+        Rendered template as a string
+    """
+    env = get_jinja_env()
+    template = env.get_template(template_name)
+    return template.render(**context)
+
+
+def format_relative_time(dt: datetime) -> str:
+    """Format datetime as relative time (e.g., '2 days ago')."""
+    now = datetime.now(timezone.utc)
+
+    # Make dt timezone-aware if it isn't
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+
+    delta = now - dt
+
+    seconds = delta.total_seconds()
+
+    if seconds < 60:
+        return "just now"
+    elif seconds < 3600:
+        minutes = int(seconds / 60)
+        return f"{minutes} minute{'s' if minutes != 1 else ''} ago"
+    elif seconds < 86400:
+        hours = int(seconds / 3600)
+        return f"{hours} hour{'s' if hours != 1 else ''} ago"
+    elif seconds < 604800:
+        days = int(seconds / 86400)
+        return f"{days} day{'s' if days != 1 else ''} ago"
+    elif seconds < 2592000:
+        weeks = int(seconds / 604800)
+        return f"{weeks} week{'s' if weeks != 1 else ''} ago"
+    elif seconds < 31536000:
+        months = int(seconds / 2592000)
+        return f"{months} month{'s' if months != 1 else ''} ago"
+    else:
+        years = int(seconds / 31536000)
+        return f"{years} year{'s' if years != 1 else ''} ago"
+
+
+def print_migration_summary(result, tour_name: str, is_dry_run: bool = False):
+    """Print a summary table of migration changes."""
+    summary_title = "Tentative Migration Summary" if is_dry_run else "Migration Summary"
+    print(f"\n  {summary_title} for {tour_name}:")
+    print(f"  {'Step':<6} {'Location':<40} {'Status':<20}")
+    print(f"  {'-'*6} {'-'*40} {'-'*20}")
+
+    prev_file = None
+
+    for update in result.updates:
+        step_num = update.step_index + 1
+
+        # Format old → new or just location
+        if update.new_location is None:
+            location = f"{update.old_location:<40}"
+            status = "❌ Would deprecate" if is_dry_run else "❌ Deprecated"
+            # Track file for next iteration
+            if ':' in update.old_location:
+                prev_file = update.old_location.rsplit(':', 1)[0]
+        elif update.was_updated:
+            # Parse old and new locations
+            old_file, old_line = update.old_location.rsplit(':', 1) if ':' in update.old_location else (update.old_location, '')
+            new_file, new_line = update.new_location.rsplit(':', 1) if ':' in update.new_location else (update.new_location, '')
+
+            # Optimize display - only show file when it changes
+            if old_file == new_file:
+                # Same file - just show line numbers
+                location = f":{old_line} → :{new_line}"
+                # If file changed from previous step, show it
+                if prev_file != old_file:
+                    location = f"{old_file}{location}"
+            else:
+                # Different files - show full locations
+                location = f"{update.old_location} → {update.new_location}"
+
+            if len(location) > 40:
+                location = location[:37] + "..."
+
+            if update.needs_review:
+                status = "⚠️  Would need review" if is_dry_run else "⚠️  Needs review"
+            else:
+                status = "✓ Would update" if is_dry_run else "✓ Updated"
+
+            prev_file = new_file
+        else:
+            # Unchanged - optimize if same file as previous
+            if ':' in update.old_location:
+                curr_file, curr_line = update.old_location.rsplit(':', 1)
+                if prev_file == curr_file:
+                    location = f":{curr_line}"
+                else:
+                    location = update.old_location
+                prev_file = curr_file
+            else:
+                location = update.old_location
+            status = "— Unchanged"
+
+        print(f"  {step_num:<6} {location:<40} {status:<20}")
+
+    print()
+
+
+def quote_with_chevrons(text: str) -> str:
+    """Quote multi-line text with markdown chevrons (>)."""
+    if not text:
+        return "> (No description)"
+    lines = text.split('\n')
+    return '\n'.join(f"> {line}" for line in lines)
+
+
+def get_code_context(repo_root: Path, file_path: str, line_num: int, commit_sha: str, context_lines: int = 7) -> str:
+    """
+    Extract code context around a line number from a specific git commit.
+
+    Args:
+        repo_root: Root of the repository
+        file_path: Relative path to file (e.g., "src/main.rs")
+        line_num: Line number (1-indexed)
+        commit_sha: Git commit SHA to read file from
+        context_lines: Number of lines before and after to include
+
+    Returns:
+        Formatted code context with line numbers
+    """
+    try:
+        from git import Repo
+
+        repo = Repo(repo_root)
+
+        # Get file content from specific commit
+        try:
+            commit = repo.commit(commit_sha)
+            file_content = commit.tree / file_path
+            lines = file_content.data_stream.read().decode('utf-8', errors='replace').splitlines()
+        except (KeyError, AttributeError):
+            return f"(File not found in commit {commit_sha[:8]}: {file_path})"
+
+        # Calculate range (1-indexed to 0-indexed)
+        start = max(0, line_num - context_lines - 1)
+        end = min(len(lines), line_num + context_lines)
+        target_idx = line_num - 1
+
+        # Build context with line numbers
+        context = []
+        for i in range(start, end):
+            line_no = i + 1
+            marker = " → " if i == target_idx else "   "
+            context.append(f"{line_no:4d}{marker}{lines[i]}")
+
+        return '\n'.join(context)
+    except Exception as e:
+        return f"(Failed to read {file_path} from commit {commit_sha[:8]}: {e})"
+
+
+def extract_frontmatter(content: str) -> dict:
+    """
+    Extract YAML frontmatter from markdown content.
+
+    Args:
+        content: Markdown content with optional frontmatter
+
+    Returns:
+        Dictionary of frontmatter values (empty if no frontmatter)
+    """
+    import yaml
+    import re
+
+    # Look for YAML frontmatter delimited by ---
+    match = re.match(r'^---\s*\n(.*?)\n---\s*\n', content, re.DOTALL)
+    if not match:
+        return {}
+
+    try:
+        frontmatter = yaml.safe_load(match.group(1))
+        return frontmatter or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def has_end_schema(content: str) -> bool:
+    """
+    Check if content has an embedded parsing schema at the end.
+
+    Args:
+        content: Markdown content
+
+    Returns:
+        True if end-schema is present
+    """
+    return '<!-- PARSING_SCHEMA' in content
+
+
+def extract_end_schema(content: str) -> Optional[ParsingSchema]:
+    """
+    Extract parsing schema from end of markdown content.
+
+    Args:
+        content: Markdown content with optional embedded schema
+
+    Returns:
+        ParsingSchema if found, None otherwise
+    """
+    import yaml
+    import re
+
+    # Look for schema in HTML comment
+    match = re.search(
+        r'<!-- PARSING_SCHEMA.*?\n(.*?)\n-->',
+        content,
+        re.DOTALL
+    )
+
+    if not match:
+        return None
+
+    try:
+        schema_yaml = match.group(1)
+        schema_data = yaml.safe_load(schema_yaml)
+        return ParsingSchema.from_dict(schema_data)
+    except Exception as e:
+        log.warning("failed_to_parse_end_schema", error=str(e))
+        return None
+
+
+def load_parsing_schema(report_content: str) -> ParsingSchema:
+    """
+    Load parsing schema using smart defaults.
+
+    Implements the refined Iteration 2 approach:
+    1. Extract frontmatter to get schema version/language
+    2. Load default schema for that version
+    3. Merge with custom end-schema if present
+
+    Args:
+        report_content: Full markdown content of review report
+
+    Returns:
+        ParsingSchema with defaults merged with any customizations
+    """
+    # 1. Extract frontmatter
+    frontmatter = extract_frontmatter(report_content)
+    schema_version = frontmatter.get('schema_version', '1.0')
+    language = frontmatter.get('language', 'en')
+
+    # 2. Load default schema for version
+    schemas_dir = Path(__file__).parent / 'schemas'
+    default_schema_path = schemas_dir / f"review_report_v{schema_version}.yaml"
+
+    if not default_schema_path.exists():
+        # Fallback to v1.0 if requested version doesn't exist
+        log.warning(
+            "schema_version_not_found",
+            requested=schema_version,
+            fallback="1.0"
+        )
+        default_schema_path = schemas_dir / "review_report_v1.0.yaml"
+
+    schema = ParsingSchema.from_yaml(default_schema_path)
+
+    # 3. Check for custom schema override
+    if frontmatter.get('custom_schema') or has_end_schema(report_content):
+        custom_schema = extract_end_schema(report_content)
+        if custom_schema:
+            schema = schema.merge(custom_schema)
+            log.info("merged_custom_schema", language=custom_schema.language)
+
+    return schema
+
+
+def generate_review_report(
+    tour_path: Path,
+    result,
+    source_commit: str,
+    target_commit: str,
+    repo_root: Path,
+    is_dry_run: bool = False,
+    no_guidance: bool = False,
+    threshold: Optional[float] = None
+) -> Optional[Path]:
+    """
+    Generate a markdown review report for migrations with low-confidence steps.
+
+    Args:
+        threshold: the ACTUAL threshold value the migration just ran with
+            (ADR-0016 QST-CONF-2). When given, the report displays this
+            value rather than independently re-reading the config file --
+            those could disagree whenever `--threshold` overrides the
+            config on the command line, showing a report that describes
+            a run that didn't happen. Falls back to reading config
+            directly only when not given, for older callers.
+
+    Returns path to generated report, or None if no review needed.
+    """
+    # Only generate if there are steps needing review
+    if result.num_needs_review == 0:
+        return None
+
+    from datetime import datetime
+    from git import Repo
+
+    tour_name = tour_path.stem  # Remove .tour extension
+    # Include target commit hash in filename for versioning
+    report_path = tour_path.parent / f"MIGRATION-REVIEW-{tour_name}-{target_commit[:8]}.md"
+
+    # Get review steps
+    review_steps = [
+        (i + 1, update) for i, update in enumerate(result.updates)
+        if update.needs_review
+    ]
+
+    # Build report content with frontmatter
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    mode = "dry-run" if is_dry_run else "live"
+
+    # Add YAML frontmatter with schema version
+    report = "---\n"
+    report += "schema_version: '1.0'\n"
+    report += "---\n\n"
+
+    # Get commit info for both source and target
+    try:
+        repo = Repo(repo_root)
+
+        # Source commit
+        source_commit_obj = repo.commit(source_commit)
+        source_timestamp = source_commit_obj.committed_datetime.strftime("%Y-%m-%d %H:%M")
+        source_desc = f"{source_commit[:8]} (committed {source_timestamp})"
+
+        # Target commit
+        target_commit_obj = repo.commit(target_commit)
+        target_timestamp = target_commit_obj.committed_datetime.strftime("%Y-%m-%d %H:%M")
+
+        # Calculate commits behind
+        try:
+            commits_behind = len(list(repo.iter_commits(f"{source_commit}..{target_commit}")))
+        except:
+            commits_behind = 0
+
+        # Check if target is HEAD
+        try:
+            head_sha = repo.head.commit.hexsha
+            if target_commit.startswith(head_sha[:8]) or head_sha.startswith(target_commit[:8]):
+                if commits_behind > 0:
+                    commits_label = "commit" if commits_behind == 1 else "commits"
+                    target_desc = f"HEAD, {target_commit[:8]} (committed {target_timestamp}), {commits_behind} {commits_label} behind"
+                else:
+                    target_desc = f"HEAD, {target_commit[:8]} (committed {target_timestamp})"
+            else:
+                target_desc = f"{target_commit[:8]} (committed {target_timestamp})"
+        except:
+            target_desc = f"{target_commit[:8]} (committed {target_timestamp})"
+    except:
+        source_desc = f"{source_commit[:8]}"
+        target_desc = f"{target_commit[:8]}"
+
+    # Conditional language based on mode
+    verb_past = "would be updated" if is_dry_run else "updated"
+    verb_need = "would need" if is_dry_run else "need"
+
+    # Render header template
+    deprecated_line = f"- ❌ **{result.num_deprecated} steps** reference deleted files" if result.num_deprecated > 0 else ""
+
+    report += render_template(
+        'review_report.md',
+        timestamp=timestamp,
+        source_desc=source_desc,
+        target_desc=target_desc,
+        mode=mode,
+        tour_name=tour_path.name,
+        total_steps=len(result.updates),
+        num_updated_success=result.num_updated - result.num_needs_review,
+        verb_past=verb_past,
+        num_needs_review=result.num_needs_review,
+        verb_need=verb_need,
+        num_unchanged=len(result.updates) - result.num_updated,
+        deprecated_line=deprecated_line
+    )
+
+    # Add guidance sections unless --no-guidance flag is set
+    if not no_guidance:
+        # Calculate relative path from repo root for documentation
+        try:
+            report_name_relative = str(report_path.relative_to(repo_root))
+        except ValueError:
+            # If path is not relative to repo_root, use name only
+            report_name_relative = report_path.name
+
+        # Render unified guidance template with mode-specific content
+        report += render_template(
+            'guidance.md',
+            is_dry_run=is_dry_run,
+            report_name=report_name_relative,
+            tour_path=tour_path
+        )
+
+    report += """
+
+## Steps Needing Review
+
+"""
+
+    # Add each review step
+    for step_num, update in review_steps:
+        step = result.tour.steps[update.step_index]
+
+        # Parse old and new locations
+        old_parts = update.old_location.split(':')
+        old_file = old_parts[0]
+        old_line = int(old_parts[1]) if len(old_parts) > 1 else None
+
+        if update.new_location:
+            new_parts = update.new_location.split(':')
+            new_file = new_parts[0]
+            new_line = int(new_parts[1]) if len(new_parts) > 1 else None
+        else:
+            new_file = "(file deleted)"
+            new_line = None
+
+        # Get code context for old and new locations (from specific commits)
+        old_context = get_code_context(repo_root, old_file, old_line, source_commit) if old_line else "(No line number)"
+        new_context = get_code_context(repo_root, new_file, new_line, target_commit) if new_line and update.new_location else "(File deleted)"
+
+        # Quote the description with chevrons
+        quoted_description = quote_with_chevrons(step.description)
+
+        # Build absolute paths for clickable links
+        abs_old_file = (repo_root / old_file).resolve()
+        abs_new_file = (repo_root / new_file).resolve() if update.new_location else abs_old_file
+
+        # Create VS Code URLs for clickable links
+        vscode_old_url = f"vscode://file/{abs_old_file}:{old_line}:1"
+        vscode_new_url = f"vscode://file/{abs_new_file}:{new_line if new_line else 1}:1"
+
+        hunk_interior_warning = (
+            "\n**⚠️  Verify before accepting** -- this position came from an "
+            "unverified positional guess inside a changed region (`hunk_interior`), "
+            "not from content matching. ADR-0016's calibration study measured "
+            "this class of guess at 33% correct (2 of 6 labeled cases) -- treat "
+            "the tentative fields below as a weak starting point, not a likely-"
+            "correct default.\n"
+            if update.migration_result.method == 'hunk_interior' else ""
+        )
+
+        report += f"""### Step {step_num}: {update.old_location} → {update.new_location} ({int(update.migration_result.confidence * 100)}% confidence) ⚠️
+{hunk_interior_warning}
+---
+
+#### Review Status
+
+- **Status**: [ ] Not reviewed
+- **Tentative file**: `{new_file if update.new_location else old_file}`
+- **Tentative line**: `{new_line if update.new_location else old_line}`
+- **Confidence**: {int(update.migration_result.confidence * 100)}%
+- **Modified Description**: [ ] (Check this to edit the tour step description)
+
+**Edited Description**:
+
+> (Edit the step description here if you checked "Modified Description" above)
+
+**Note**: If the tentative location is incorrect, you can edit the "Tentative file" and "Tentative line" fields above. If you want to update the step description, check "Modified Description" and edit the quoted text above. Then apply using `codetour-cli apply-review`.
+
+---
+
+#### Original Tour Step Description
+
+{quoted_description}
+
+**Quick Links:**
+- [Open old location in editor]({vscode_old_url}) (`{old_file}:{old_line}`)
+- [Open new location in editor]({vscode_new_url}) (`{new_file}:{new_line if new_line else 'N/A'}`)
+
+---
+
+#### Migration Details
+
+- **Old location**: [{update.old_location}]({vscode_old_url}) (commit {source_commit[:8]})
+- **New location**: [{update.new_location if update.new_location else "(file deleted)"}]({vscode_new_url}) (commit {target_commit[:8]})
+- **Reason for review**: Low confidence - {update.migration_result.method} method
+
+---
+
+#### Code Context at Old Location (commit {source_commit[:8]})
+
+File: [{old_file}:{old_line}]({vscode_old_url})
+
+```
+{old_context}
+```
+
+---
+
+#### Code Context at New Location (commit {target_commit[:8]})
+
+File: [{new_file}:{new_line if new_line else 'N/A'}]({vscode_new_url})
+
+```
+{new_context}
+```
+
+(Lines marked with → indicate the tour step location)
+
+---
+
+#### How to Review
+
+1. **Examine the code contexts above**:
+   - Compare old location ({source_commit[:8]}) with new location ({target_commit[:8]})
+   - Does the new location match the step's original intent?
+   - Click the links above to open files in VS Code
+
+2. **Verify in editor**:
+   - Click [Open new location in editor]({vscode_new_url})
+   - Or run: `code -g {update.new_location if update.new_location else update.old_location}`
+
+3. **Make your decision**:
+   - **If correct**: Change `[ ]` to `[x]` in Review Status above
+   - **If wrong**: Edit the "Tentative file" and "Tentative line" fields above with correct values
+   - Then run: `codetour-cli apply-review {tour_path.relative_to(repo_root)}`
+
+---
+
+"""
+
+    # Add appendix with all steps
+    report += """## Appendix: All Steps
+
+| Step | File | Old Line | New Line | Status | Confidence |
+|------|------|----------|----------|--------|------------|
+"""
+
+    for i, update in enumerate(result.updates, 1):
+        old_parts = update.old_location.split(':') if update.old_location else ['', '']
+        old_file = old_parts[0]
+        old_line = old_parts[1] if len(old_parts) > 1 else ''
+
+        if update.new_location:
+            new_parts = update.new_location.split(':')
+            new_file = new_parts[0]
+            new_line = new_parts[1] if len(new_parts) > 1 else ''
+        else:
+            new_file = '(deleted)'
+            new_line = ''
+
+        if update.new_location is None:
+            status = "**Deprecated**"
+        elif update.needs_review:
+            status = "**Review**"
+        elif update.was_updated:
+            status = "Updated"
+        else:
+            status = "Unchanged"
+
+        confidence = f"{int(update.migration_result.confidence * 100)}%" if update.migration_result.confidence is not None else "N/A"
+
+        report += f"| {i} | {old_file} | {old_line} | {new_line} | {status} | {confidence} |\n"
+
+    report += "\n"
+
+    # Add configuration appendix
+    try:
+        config_path = repo_root / ".tours" / "codetour.yaml"
+        if not config_path.exists():
+            config_path = repo_root / "codetour.yaml"
+
+        if threshold is not None:
+            # The value the migration actually just ran with (ADR-0016
+            # QST-CONF-2) -- always prefer this over re-deriving from the
+            # config file, which could disagree if --threshold overrode it.
+            effective_threshold = threshold
+        else:
+            effective_threshold = 0.7  # default
+            if config_path.exists():
+                import yaml
+                with open(config_path) as f:
+                    config_data = yaml.safe_load(f) or {}
+                    effective_threshold = config_data.get("migration", {}).get("threshold", 0.7)
+        threshold = effective_threshold
+
+        # Build configuration appendix
+        low_conf_steps = [
+            (i+1, update) for i, update in enumerate(result.updates)
+            if update.needs_review
+        ]
+
+        if low_conf_steps:
+            confidence_list = ", ".join([
+                f"{int(update.migration_result.confidence * 100)}%"
+                for _, update in low_conf_steps
+            ])
+
+            report += f"""## Appendix: Why These Steps Need Review
+
+The {len(low_conf_steps)} step{'s' if len(low_conf_steps) != 1 else ''} flagged for review ({", ".join(f"#{num}" for num, _ in low_conf_steps)}) have confidence scores below the configured threshold.
+
+**Confidence scores**: {confidence_list}
+**Configured threshold**: {int(threshold * 100)}% (from `{config_path.relative_to(repo_root)}`{"" if config_path.exists() else ", not created yet -- this is the default"})
+
+Steps with confidence below {int(threshold * 100)}% require manual review because the migration algorithm is less certain about the correct new location. This typically happens when:
+
+- Lines were modified within a changed section (hunk_interior method)
+- Multiple similar code patterns exist
+- Significant refactoring occurred between commits
+
+**To adjust the threshold**, edit your configuration file at `{config_path.relative_to(repo_root)}`{"" if config_path.exists() else " (run `codetour-cli init` first to create it at the repo root)"}:
+
+```yaml
+migration:
+  threshold: 0.7
+```
+
+Confidence is not a continuous score -- it only ever takes one of five
+exact values: 1.0, 0.95, 0.5, 0.4, 0.0 (see `docs/adr/0016-*.md` for what
+produces each). A threshold anywhere in (0.5, 0.95) -- including the
+default 0.7 -- behaves identically, since nothing the engine produces
+falls in that range, AND steps whose location came from inside a changed
+hunk always require review regardless of this setting (a separate,
+unconditional check -- lowering the threshold cannot exempt those).
+What this setting actually changes: raise it above 0.95 to also require
+review of pattern-validated matches; lower it to 0.4 or below to stop
+flagging pattern-mismatch cases; lower it to 0 or below to ALSO stop
+flagging outright file deletions and removed lines (**not recommended**
+-- these are the cases with no location to guess at all).
+
+"""
+    except Exception as e:
+        # If we can't load config, skip the appendix
+        pass
+
+    # No embedded schema needed - frontmatter schema_version references built-in default
+    # Custom schemas can be added via end-schema when needed for internationalization
+
+    # Write report
+    report_path.write_text(report)
+
+    return report_path
+
+
+def main():
+    """Main CLI entry point."""
+    # Structured logging was never wired in before this call -- structlog's
+    # own unconfigured default prints every level (including debug) to
+    # stdout, interleaved with this CLI's human-facing output and breaking
+    # `lint --format json`'s output purity. configure_logging()'s own
+    # default routes to stderr at INFO level, same as every other command
+    # here already assumed but never enforced.
+    configure_logging()
+
+    parser = argparse.ArgumentParser(
+        prog='codetour-cli',
+        description='Maintain CodeTours as code changes',
+        epilog='''
+Quick Start:
+  codetour-cli status                          # See what needs updating (2 seconds)
+  codetour-cli migrate                         # Fix everything (10 seconds)
+  git diff .tours/                             # Review changes
+  git add .tours/ && git commit -m "chore: update tours"
+
+Examples:
+  codetour-cli status                          # Check all tours
+  codetour-cli migrate                         # Migrate all out-of-date tours
+  codetour-cli migrate .tours/api-guide.tour   # Migrate specific tour
+        ''',
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+
+    subparsers = parser.add_subparsers(dest='command', help='Available commands')
+
+    # init command
+    subparsers.add_parser(
+        'init',
+        help='Initialize CodeTour CLI in current repository'
+    )
+
+    # status command
+    subparsers.add_parser(
+        'status',
+        help='Show health of all tours in repository'
+    )
+
+    # check command
+    check_parser = subparsers.add_parser(
+        'check',
+        help='Validate tours without migrating'
+    )
+    check_parser.add_argument(
+        'tour_file',
+        type=str,
+        nargs='?',  # Optional argument
+        help='Path to .tour file to check (default: check all tours)'
+    )
+
+    # lint command (ADR-0014: step-level checks against filesystem ground truth)
+    lint_parser = subparsers.add_parser(
+        'lint',
+        help='Lint tours against the workspace (missing files, stale lines, bad patterns)'
+    )
+    lint_parser.add_argument(
+        'paths',
+        type=str,
+        nargs='*',
+        help='Tour files or directories to lint (default: discover the repository tours directory)'
+    )
+    lint_parser.add_argument(
+        '--format',
+        choices=['human', 'json'],
+        default='human',
+        dest='format',
+        help='Output format (default: human)'
+    )
+    lint_parser.add_argument(
+        '--strict',
+        action='store_true',
+        dest='strict',
+        help='Exit non-zero on warnings too, not just errors'
+    )
+
+    # undo command
+    undo_parser = subparsers.add_parser(
+        'undo',
+        help='Restore tours from backup files'
+    )
+    undo_parser.add_argument(
+        'tour_file',
+        type=str,
+        nargs='?',  # Optional argument
+        help='Path to .tour file to restore (default: restore all with backups)'
+    )
+
+    # apply-review command
+    apply_review_parser = subparsers.add_parser(
+        'apply-review',
+        help='Apply corrections from a migration review report'
+    )
+    apply_review_parser.add_argument(
+        'report_file',
+        type=str,
+        help='Path to migration review report (.md file)'
+    )
+    apply_review_parser.add_argument(
+        '--yes', '-y',
+        action='store_true',
+        dest='auto_approve',
+        help='Automatically approve all changes (skip confirmation prompts)'
+    )
+
+    # migrate command
+    migrate_parser = subparsers.add_parser(
+        'migrate',
+        help='Migrate CodeTours to current HEAD'
+    )
+    migrate_parser.add_argument(
+        'tour_file',
+        type=str,
+        nargs='?',  # Optional argument
+        help='Path to .tour file to migrate (default: migrate all out-of-date tours)'
+    )
+    migrate_parser.add_argument(
+        '--from-commit',
+        type=str,
+        dest='from_commit',
+        help='Override source commit detection (default: auto-detect via git log)'
+    )
+    migrate_parser.add_argument(
+        '--to-commit',
+        type=str,
+        dest='to_commit',
+        default='HEAD',
+        help='Target commit to migrate to (default: HEAD)'
+    )
+    migrate_parser.add_argument(
+        '--threshold',
+        type=float,
+        dest='threshold',
+        help=(
+            'Confidence threshold for auto-applying changes (default: from '
+            'config, 0.7). Confidence only ever takes 5 exact values -- '
+            'anything in (0.5, 0.95) behaves like the default; see '
+            'docs/adr/0016-*.md before tuning this expecting a smooth dial'
+        )
+    )
+    migrate_parser.add_argument(
+        '--no-backup',
+        action='store_true',
+        dest='no_backup',
+        help='Do not create backup files'
+    )
+    migrate_parser.add_argument(
+        '--interactive',
+        action='store_true',
+        dest='interactive',
+        help='Interactively select tours to migrate'
+    )
+    migrate_parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        dest='dry_run',
+        help='Preview changes without modifying files'
+    )
+    migrate_parser.add_argument(
+        '--no-guidance',
+        action='store_true',
+        dest='no_guidance',
+        help='Suppress instructional text in review reports'
+    )
+    migrate_parser.add_argument(
+        '--no-lint',
+        action='store_true',
+        dest='no_lint',
+        help='Skip the advisory post-migration lint pass (ADR-0014)'
+    )
+
+    args = parser.parse_args()
+
+    # Load configuration (merge with command-line args)
+    config = load_config()
+
+    # Require a command
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    # Handle commands
+    if args.command == 'init':
+        sys.exit(init_command(args, config))
+    elif args.command == 'status':
+        sys.exit(status_command(args, config))
+    elif args.command == 'check':
+        sys.exit(check_command(args, config))
+    elif args.command == 'undo':
+        sys.exit(undo_command(args, config))
+    elif args.command == 'apply-review':
+        sys.exit(apply_review_command(args, config))
+    elif args.command == 'lint':
+        sys.exit(lint_command(args, config))
+    elif args.command == 'migrate':
+        sys.exit(migrate_command(args, config))
+
+    parser.print_help()
+    sys.exit(1)
+
+
+def _quiet_repo_root(start: Optional[Path] = None) -> Path:
+    """Walk up from `start` (or cwd, if not given) to the nearest .git, silently.
+
+    Deliberately not find_repo_root(): that helper structlogs an [error] line
+    to stdout in non-git directories, which would pollute `lint --format json`
+    output (and lint should run quietly anywhere).
+
+    `start` matters whenever the path being linted isn't inside the CWD's own
+    repo -- e.g. `codetour-cli lint /some/other/repo/.tours/foo.tour` run from
+    a different directory. CWD-only derivation silently resolved every
+    `step.file` against the WRONG repo in that case (Cicerone's gate finding,
+    Mission 7). Callers that already know the real repo root (migrate, which
+    resolved one long before any lint pass runs) should pass it directly
+    rather than have this re-derive it from cwd at all.
+    """
+    root = (start or Path.cwd()).resolve()
+    if root.is_file():
+        root = root.parent
+    for candidate in (root, *root.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return Path.cwd().resolve()
+
+
+def _post_migration_lint(tour_paths, config: dict, no_lint: bool, dry_run: bool, repo_root: Path) -> None:
+    """Warn-only lint pass over freshly migrated tours (ADR-0014 QST-MIGRATE-HOOK).
+
+    The migration engine's confidence scoring is probabilistic; this is the
+    hard check behind it. Never changes the migrate exit code, prints nothing
+    when clean, suppressed by --no-lint, skipped on dry runs (nothing was
+    written to lint).
+
+    `repo_root` is the caller's own already-resolved repo root (migrate always
+    has one by this point) -- passed through rather than re-derived from cwd,
+    so this lint pass checks the same repo migrate just touched, not whatever
+    happens to be the working directory's own repo.
+    """
+    if no_lint or dry_run or not tour_paths:
+        return
+    try:
+        from codetour_cli.lint import lint_collection
+
+        findings = lint_collection([Path(p) for p in tour_paths], repo_root,
+                                   severities=(config.get('lint') or {}).get('severities') or {})
+    except Exception:
+        return  # advisory pass: never let lint break a completed migration
+    if not findings:
+        return
+    errors = [f for f in findings if f.severity == "error"]
+    warns = len(findings) - len(errors)
+    print(f"\n🔎 Post-migration lint: {len(errors)} error(s), {warns} warning(s) "
+          f"(advisory — exit code unaffected; suppress with --no-lint)")
+    for f in errors[:5]:
+        loc = f" (step {f.step_index + 1})" if f.step_index is not None else ""
+        print(f"  ✗ [{f.check_id}]{loc} {Path(f.tour_file).name}: {f.message}")
+    if len(errors) > 5:
+        print(f"  … and {len(errors) - 5} more error(s)")
+    print("  Full details: codetour-cli lint")
+
+
+def lint_command(args, config: dict) -> int:
+    """
+    Execute the lint command (ADR-0014).
+
+    Step-level validation of tours against filesystem ground truth — the
+    algorithmic half of the authoring duo (models write tours, this checks
+    them). Reference-resolution linting (adr:...#qst-... handles) is
+    deliberately out of scope; that belongs to the vscode crew's tour-lint.
+
+    Exit codes: 0 = clean, 1 = findings at error level (any finding with
+    --strict), 2 = usage/environment error.
+    """
+    import json as _json
+
+    from codetour_cli.lint import has_errors, lint_collection
+
+    # Derived from the given path (a tour file or directory) upward when one
+    # is given, not cwd -- `codetour-cli lint /other/repo/.tours/x.tour` run
+    # from a different directory used to silently check `step.file` against
+    # the WRONG repo (cwd's), not the tour's own. cwd remains the fallback
+    # for the no-args "lint everything in .tours/" case, where it's correct
+    # by definition.
+    repo_root = _quiet_repo_root(Path(args.paths[0]) if args.paths else None)
+
+    if args.paths:
+        tour_paths = []
+        for raw in args.paths:
+            p = Path(raw)
+            if p.is_dir():
+                tour_paths.extend(scan_tours(p))
+            elif p.is_file():
+                tour_paths.append(p)
+            else:
+                print(f"❌ No such file or directory: {raw}")
+                return 2
+    else:
+        tours_dir = find_tours_directory(repo_root)
+        if not tours_dir:
+            print("❌ No tours directory found; pass tour files or directories explicitly")
+            return 2
+        tour_paths = scan_tours(tours_dir)
+
+    if not tour_paths:
+        print("No tour files found to lint.")
+        return 0
+
+    severities = (config.get('lint') or {}).get('severities') or {}
+    findings = lint_collection(tour_paths, repo_root, severities=severities)
+
+    if args.format == 'json':
+        print(_json.dumps([f.to_dict() for f in findings], indent=2))
+    else:
+        if not findings:
+            print(f"✓ {len(tour_paths)} tour(s) clean — no findings")
+        else:
+            by_file: dict = {}
+            for f in findings:
+                by_file.setdefault(f.tour_file, []).append(f)
+            for tour_file, file_findings in sorted(by_file.items()):
+                print(f"\n{tour_file}:")
+                for f in file_findings:
+                    icon = "✗" if f.severity == "error" else "⚠"
+                    # 1-based step display, matching review reports
+                    loc = f" (step {f.step_index + 1})" if f.step_index is not None else ""
+                    print(f"  {icon} [{f.check_id}]{loc} {f.message}")
+            errors = sum(1 for f in findings if f.severity == "error")
+            warns = len(findings) - errors
+            print(f"\n{errors} error(s), {warns} warning(s) across {len(tour_paths)} tour(s)")
+
+    return 1 if has_errors(findings, strict=args.strict) else 0
+
+
+def init_command(args, config: dict) -> int:
+    """
+    Execute the init command.
+
+    Initializes CodeTour CLI in the current repository:
+    - Detects git repository
+    - Finds or creates .tours/ directory
+    - Scans for existing tours
+    - Generates codetour.yaml configuration
+
+    Returns:
+        Exit code (0 = success, 2 = error)
+    """
+    print("🔍 Initializing CodeTour CLI...\n")
+
+    # Check if we're in a git repository
+    try:
+        repo_root = find_repo_root()
+        repo = Repo(repo_root)
+        print(f"✓ Detected git repository: {repo_root}")
+
+        # Show remote if available
+        try:
+            if repo.remotes:
+                remote_url = repo.remotes.origin.url if 'origin' in [r.name for r in repo.remotes] else repo.remotes[0].url
+                print(f"  Remote: {remote_url}")
+        except:
+            pass  # No remote configured, that's fine
+
+    except InvalidGitRepositoryError:
+        print("❌ Not a git repository", file=sys.stderr)
+        print(file=sys.stderr)
+        print("CodeTour CLI requires git to track tour drift.", file=sys.stderr)
+        print("Initialize git first:", file=sys.stderr)
+        print("  git init", file=sys.stderr)
+        print("  git add .", file=sys.stderr)
+        print('  git commit -m "Initial commit"', file=sys.stderr)
+        return 2
+
+    # Find or create .tours/ directory
+    tours_dir = find_tours_directory(repo_root)
+
+    if tours_dir is None:
+        # Create .tours/ directory
+        tours_dir = repo_root / ".tours"
+        tours_dir.mkdir(parents=True, exist_ok=True)
+        print(f"✓ Created tours directory: {tours_dir.relative_to(repo_root)}")
+    else:
+        print(f"✓ Found tours directory: {tours_dir.relative_to(repo_root)}")
+
+    # Scan for existing tours
+    tour_files = scan_tours(tours_dir)
+    num_tours = len(tour_files)
+
+    if num_tours > 0:
+        print(f"✓ Found {num_tours} existing tour{'s' if num_tours != 1 else ''}")
+        for tour_file in tour_files[:5]:  # Show first 5
+            print(f"  • {tour_file.name}")
+        if num_tours > 5:
+            print(f"  ... and {num_tours - 5} more")
+    else:
+        print("  No existing tours found")
+
+    # Generate configuration file
+    config_path = repo_root / "codetour.yaml"
+
+    if config_path.exists():
+        print(f"\n⚠  Configuration file already exists: {config_path.relative_to(repo_root)}")
+        print("  Skipping generation (delete file to regenerate)")
+    else:
+        generate_config_file(config_path)
+        print(f"\n✓ Generated configuration: {config_path.relative_to(repo_root)}")
+
+    # Summary and next steps
+    print("\n" + "─" * 50)
+    print("✓ CodeTour CLI initialized successfully!")
+    print()
+    print("Configuration:")
+    print(f"  • Repository: {repo_root}")
+    print(f"  • Tours directory: {tours_dir.relative_to(repo_root)}")
+    print(f"  • Config file: codetour.yaml")
+    print()
+    print("Next steps:")
+    if num_tours > 0:
+        print("  codetour-cli status    # Check tour health")
+        print("  codetour-cli migrate   # Update out-of-date tours")
+    else:
+        print("  # Create tours using VS Code CodeTour extension")
+        print("  # Or add .tour files to .tours/ directory")
+        print()
+        print("  codetour-cli status    # Check tours when ready")
+
+    return 0
+
+
+def status_command(args, config: dict) -> int:
+    """
+    Execute the status command.
+
+    Shows health of all tours in the repository.
+
+    Returns:
+        Exit code (0 = all up to date, 1 = some need updates, 2 = error)
+    """
+    # Warn if no config file
+    try:
+        repo_root = find_repo_root()
+        config_path = repo_root / "codetour.yaml"
+        if not config_path.exists():
+            print("ℹ️  No configuration file found. Run 'codetour-cli init' to create one.")
+            print()
+    except:
+        pass  # If we can't find repo, discover_repository will fail below
+
+    try:
+        # Discover repository and tours
+        repo_info = discover_repository()
+    except (InvalidGitRepositoryError, ValueError) as e:
+        print(f"❌ {e}", file=sys.stderr)
+        return 2
+
+    # Display summary header
+    num_tours = len(repo_info.tours)
+    if num_tours == 0:
+        print(f"📊 No tours found in {repo_info.tours_dir}")
+        print()
+        print("Create a tour file in .tours/ or run: codetour init")
+        return 2
+
+    print(f"📊 Found {num_tours} tour{'s' if num_tours != 1 else ''} in {repo_info.tours_dir.relative_to(repo_info.repo_path)}")
+    print()
+
+    # Display each tour
+    num_up_to_date = 0
+    num_need_update = 0
+
+    for tour_info in repo_info.tours:
+        tour_filename = tour_info.path.name
+        up_to_date = is_tour_up_to_date(tour_info)
+
+        if up_to_date:
+            num_up_to_date += 1
+            status_icon = "✅"
+        else:
+            num_need_update += 1
+            status_icon = "⚠️ "
+
+        # Tour header
+        print(f"  {status_icon} {tour_filename}")
+        print(f"     Title: \"{tour_info.tour.title}\"")
+        print(f"     Steps: {len(tour_info.tour.steps)}")
+
+        # Format timestamp
+        time_ago = format_relative_time(tour_info.last_modified) if tour_info.last_modified else "unknown"
+        print(f"     Last updated: {tour_info.source_commit[:8]} ({time_ago}, {tour_info.source_method}, {tour_info.source_confidence:.0%} confidence)")
+
+        # Show code change timestamp
+        try:
+            from git import Repo
+            repo = Repo(repo_info.repo_path)
+            head_commit = repo.head.commit
+            head_time_ago = format_relative_time(head_commit.committed_datetime)
+            print(f"     Code changed: {tour_info.commits_behind} commit{'s' if tour_info.commits_behind != 1 else ''} behind HEAD (last change {head_time_ago})")
+        except:
+            print(f"     Code changed: {tour_info.commits_behind} commit{'s' if tour_info.commits_behind != 1 else ''} behind HEAD")
+
+        if not up_to_date:
+            print(f"     Action: codetour-cli migrate {tour_info.path.relative_to(repo_info.repo_path)}")
+
+        print()
+
+    # Summary
+    print(f"Summary: {num_up_to_date} up to date, {num_need_update} need{'s' if num_need_update == 1 else ''} update")
+
+    # Exit code
+    if num_need_update > 0:
+        return 1  # Some tours need updates
+    else:
+        return 0  # All up to date
+
+
+def check_command(args, config: dict) -> int:
+    """
+    Execute the check command.
+
+    Validates tours without migrating them.
+
+    Returns:
+        Exit code (0 = all valid, 1 = issues found, 2 = error)
+    """
+    try:
+        repo_root = find_repo_root()
+        tours_dir = find_tours_directory(repo_root)
+
+        if tours_dir is None:
+            print("❌ No .tours directory found", file=sys.stderr)
+            return 2
+
+    except (InvalidGitRepositoryError, ValueError) as e:
+        print(f"❌ {e}", file=sys.stderr)
+        return 2
+
+    # Load specific tour or all tours
+    if args.tour_file:
+        tour_path = Path(args.tour_file)
+        if not tour_path.exists():
+            print(f"❌ Tour file not found: {tour_path}", file=sys.stderr)
+            return 2
+
+        try:
+            tour = Tour.from_file(tour_path)
+            tours_to_check = [(tour_path, tour)]
+        except Exception as e:
+            print(f"❌ Failed to load tour: {e}", file=sys.stderr)
+            return 2
+    else:
+        # Check all tours
+        try:
+            tours_to_check = []
+            for tour_file in tours_dir.glob("*.tour"):
+                try:
+                    tour = Tour.from_file(tour_file)
+                    tours_to_check.append((tour_file, tour))
+                except Exception as e:
+                    print(f"⚠️  Skipping invalid tour {tour_file.name}: {e}")
+        except Exception as e:
+            print(f"❌ Failed to scan tours: {e}", file=sys.stderr)
+            return 2
+
+    if not tours_to_check:
+        print("ℹ️  No tours found to check")
+        return 0
+
+    print(f"🔍 Checking {len(tours_to_check)} tour{'s' if len(tours_to_check) != 1 else ''}...\n")
+
+    total_steps = 0
+    total_valid = 0
+    total_invalid_file = 0
+    total_invalid_line = 0
+    tours_with_issues = []
+
+    for tour_path, tour in tours_to_check:
+        tour_name = tour_path.name
+        step_issues = []
+
+        for i, step in enumerate(tour.steps, 1):
+            total_steps += 1
+
+            # Skip steps without file reference
+            if not step.file:
+                total_valid += 1
+                continue
+
+            # Check if file exists
+            file_path = repo_root / step.file
+            if not file_path.exists():
+                total_invalid_file += 1
+                step_issues.append((i, f"File not found: {step.file}"))
+                continue
+
+            # Check if line number is valid
+            if step.line is not None:
+                try:
+                    with open(file_path, 'r') as f:
+                        lines = f.readlines()
+                        if step.line < 1 or step.line > len(lines):
+                            total_invalid_line += 1
+                            step_issues.append((i, f"Line {step.line} out of bounds (file has {len(lines)} lines)"))
+                            continue
+                except Exception as e:
+                    step_issues.append((i, f"Failed to read file: {e}"))
+                    total_invalid_file += 1
+                    continue
+
+            total_valid += 1
+
+        # Report issues for this tour
+        if step_issues:
+            tours_with_issues.append(tour_name)
+            print(f"⚠️  {tour_name}:")
+            for step_num, issue in step_issues:
+                print(f"    Step {step_num}: {issue}")
+            print()
+        else:
+            print(f"✓ {tour_name}: All {len(tour.steps)} steps valid")
+
+    # Summary
+    print()
+    if tours_with_issues:
+        print(f"Summary: {total_valid}/{total_steps} steps valid")
+        print(f"  ⚠️  {total_invalid_file} steps reference missing files")
+        print(f"  ⚠️  {total_invalid_line} steps reference invalid line numbers")
+        print(f"  ⚠️  {len(tours_with_issues)} tour{'s' if len(tours_with_issues) != 1 else ''} with issues")
+        print()
+        print("Run 'codetour-cli migrate' to update tours")
+        return 1
+    else:
+        print(f"✓ All {total_steps} steps valid across {len(tours_to_check)} tour{'s' if len(tours_to_check) != 1 else ''}")
+        return 0
+
+
+def undo_command(args, config: dict) -> int:
+    """
+    Execute the undo command.
+
+    Restores tours from backup files.
+
+    Returns:
+        Exit code (0 = success, 2 = error)
+    """
+    try:
+        repo_root = find_repo_root()
+        tours_dir = find_tours_directory(repo_root)
+
+        if tours_dir is None:
+            print("❌ No .tours directory found", file=sys.stderr)
+            return 2
+
+    except (InvalidGitRepositoryError, ValueError) as e:
+        print(f"❌ {e}", file=sys.stderr)
+        return 2
+
+    # If specific file provided, restore just that one
+    if args.tour_file:
+        tour_path = Path(args.tour_file)
+        backup_path = tour_path.with_suffix('.tour.backup')
+
+        if not backup_path.exists():
+            print(f"❌ No backup found for {tour_path.name}", file=sys.stderr)
+            print(f"   Expected: {backup_path}", file=sys.stderr)
+            return 2
+
+        # Restore from backup
+        import shutil
+        shutil.copy2(backup_path, tour_path)
+        backup_path.unlink()  # Remove backup after restoring
+
+        print(f"✓ Restored {tour_path.name} from backup")
+        print(f"  Backup file removed: {backup_path.name}")
+        return 0
+
+    # Otherwise, restore all tours with backups
+    backup_files = list(tours_dir.glob("*.tour.backup"))
+
+    if not backup_files:
+        print("ℹ️  No backup files found in .tours/")
+        return 0
+
+    print(f"📁 Found {len(backup_files)} backup file{'s' if len(backup_files) != 1 else ''}\n")
+
+    restored = []
+    for backup_path in backup_files:
+        # Remove .backup suffix to get .tour file
+        tour_path = backup_path.with_suffix('')
+        tour_name = tour_path.name
+
+        try:
+            import shutil
+            shutil.copy2(backup_path, tour_path)
+            backup_path.unlink()
+            restored.append(tour_name)
+            print(f"✓ Restored {tour_name}")
+        except Exception as e:
+            print(f"❌ Failed to restore {tour_name}: {e}")
+
+    print()
+    print(f"✓ Restored {len(restored)} tour{'s' if len(restored) != 1 else ''} from backup")
+    print("  All backup files have been removed")
+
+    return 0
+
+
+def apply_review_command(args, config: dict) -> int:
+    """
+    Execute the apply-review command.
+
+    Parses a migration review report using schema-based parsing and applies
+    the corrected locations and descriptions to the tour file.
+
+    Returns:
+        Exit code (0 = success, 2 = error)
+    """
+    from codetour_cli.review_parser import parse_review_report
+    from codetour_cli.description_validator import (
+        validate_edited_description,
+        format_validation_message
+    )
+    import difflib
+
+    report_path = Path(args.report_file)
+    auto_approve = getattr(args, 'auto_approve', False)
+
+    if not report_path.exists():
+        print(f"❌ Review report not found: {report_path}", file=sys.stderr)
+        return 2
+
+    try:
+        repo_root = find_repo_root()
+    except (InvalidGitRepositoryError, ValueError) as e:
+        print(f"❌ {e}", file=sys.stderr)
+        return 2
+
+    # Parse review report using schema-based parser
+    try:
+        review = parse_review_report(report_path)
+    except Exception as e:
+        print(f"❌ Failed to parse review report: {e}", file=sys.stderr)
+        log.error("parse_error", error=str(e), path=str(report_path))
+        return 2
+
+    # Find tour file
+    tours_dir = find_tours_directory(repo_root)
+    if tours_dir is None:
+        print("❌ No .tours directory found", file=sys.stderr)
+        return 2
+
+    tour_path = tours_dir / review.tour_name
+    if not tour_path.exists():
+        print(f"❌ Tour file not found: {tour_path}", file=sys.stderr)
+        return 2
+
+    # Load tour file
+    try:
+        tour = Tour.from_file(tour_path)
+    except Exception as e:
+        print(f"❌ Failed to load tour: {e}", file=sys.stderr)
+        return 2
+
+    # Get only reviewed steps (checkbox checked)
+    corrected_steps = review.get_corrected_steps()
+
+    if not corrected_steps:
+        print("ℹ️  No corrections found in review report")
+        print("   The report may not have been edited, or no checkboxes were marked")
+        print("   Tip: Check the 'Status' checkbox for steps you want to apply")
+        return 0
+
+    # Apply corrections
+    print(f"📝 Applying corrections from review report\n")
+    print(f"Tour: {review.tour_name}")
+    print(f"Corrections to apply: {len(corrected_steps)}\n")
+
+    # Separate deletions from updates
+    deletions = [s for s in corrected_steps if s.is_marked_for_deletion()]
+    updates = [s for s in corrected_steps if not s.is_marked_for_deletion()]
+
+    # Apply updates first
+    applied_updates = 0
+    applied_descriptions = 0
+
+    # Surgical-edit operations, tracked in parallel with the Pydantic-model
+    # mutations below (ADR-0013 Phase 2b) -- one entry per mutation that
+    # actually gets applied, using ORIGINAL step indices as json_source_edit
+    # paths (Round 4 §1's coordinate-frame contract: these never need to
+    # account for other operations in the batch, regardless of order).
+    # Falls back to the existing full-rewrite `tour.save()` below if surgical
+    # editing raises or fails validation for any reason.
+    surgical_ops: list = []
+
+    for step_review in updates:
+        step_idx = step_review.step_number - 1
+
+        if step_idx < 0 or step_idx >= len(tour.steps):
+            print(f"⚠️  Step {step_review.step_number}: Out of range (tour has {len(tour.steps)} steps), skipping")
+            continue
+
+        step = tour.steps[step_idx]
+        old_file = step.file
+        old_line = step.line
+
+        # Update location
+        step.file = step_review.tentative_file
+        step.line = step_review.tentative_line
+        surgical_ops.append(("replace", f"/steps/{step_idx}/file", step_review.tentative_file))
+        surgical_ops.append(("replace", f"/steps/{step_idx}/line", step_review.tentative_line))
+
+        print(f"  ✓ Step {step_review.step_number}: {old_file}:{old_line} → {step_review.tentative_file}:{step_review.tentative_line}")
+        applied_updates += 1
+
+        # Update description if edited
+        if step_review.description_edited and step_review.edited_description:
+            old_description = step.description
+            new_description = step_review.edited_description.strip()
+
+            # Validate edited description
+            validation = validate_edited_description(new_description, old_description)
+
+            # Log info-level metrics
+            for info_msg in validation.info:
+                log.info("description_edit_info", step=step_review.step_number, message=info_msg)
+
+            # Check for hard errors
+            if not validation.is_valid:
+                print(format_validation_message(step_review.step_number, validation))
+                print(f"     Skipped description edit for step {step_review.step_number}")
+                log.warning(
+                    "description_edit_failed_validation",
+                    step=step_review.step_number,
+                    errors=validation.errors
+                )
+                continue  # Skip this description edit
+
+            # Check for warnings
+            if validation.warnings and not auto_approve:
+                print(format_validation_message(step_review.step_number, validation))
+                print()
+                response = input(f"  Continue with this change? [y/N]: ")
+                if response.lower() != 'y':
+                    print(f"  Skipped description edit for step {step_review.step_number}")
+                    log.info("description_edit_declined", step=step_review.step_number)
+                    continue  # Skip this description edit
+
+            # Apply the description update
+            if old_description != new_description:
+                step.description = new_description
+                surgical_ops.append(("replace", f"/steps/{step_idx}/description", new_description))
+
+                # Show diff
+                if validation.warnings and auto_approve:
+                    print(f"  ⚠️  Step {step_review.step_number}: Description changed significantly")
+                    print(f"      ({validation.similarity:.0%} similarity, applied anyway with --yes)")
+                else:
+                    print(f"    📝 Description updated ({validation.similarity:.0%} similarity)")
+
+                # Show diff details
+                diff = difflib.unified_diff(
+                    old_description.splitlines(keepends=True),
+                    new_description.splitlines(keepends=True),
+                    lineterm='',
+                    n=1
+                )
+                for line in diff:
+                    if line.startswith('+++') or line.startswith('---'):
+                        continue
+                    if line.startswith('+'):
+                        print(f"       {line}")
+                    elif line.startswith('-'):
+                        print(f"       {line}")
+
+                applied_descriptions += 1
+
+                log.info(
+                    "description_updated",
+                    step=step_review.step_number,
+                    old_length=len(old_description),
+                    new_length=len(new_description),
+                    similarity=validation.similarity
+                )
+
+    # Apply deletions in reverse order to avoid index shifting
+    applied_deletions = 0
+    for step_review in sorted(deletions, key=lambda s: s.step_number, reverse=True):
+        step_idx = step_review.step_number - 1
+
+        if step_idx < 0 or step_idx >= len(tour.steps):
+            print(f"⚠️  Step {step_review.step_number}: Out of range (tour has {len(tour.steps)} steps), skipping")
+            continue
+
+        step = tour.steps[step_idx]
+        print(f"  🗑️  Step {step_review.step_number}: {step.file}:{step.line} (marked for deletion)")
+
+        # Remove step from tour
+        tour.steps.pop(step_idx)
+        surgical_ops.append(("remove", f"/steps/{step_idx}"))
+        applied_deletions += 1
+
+    applied = applied_updates + applied_deletions
+
+    if applied == 0:
+        print("\nℹ️  No corrections applied")
+        return 0
+
+    # Save tour file
+    try:
+        # Create backup first
+        backup_path = tour_path.with_suffix('.tour.backup')
+        if not backup_path.exists():  # Don't overwrite existing backups
+            import shutil
+            shutil.copy2(tour_path, backup_path)
+            print(f"\n  📁 Created backup: {backup_path.name}")
+
+        # ADR-0013 Phase 2b: try surgical (byte-preserving) editing first, on
+        # the ORIGINAL on-disk bytes -- tour_path hasn't been written yet at
+        # this point, so JSONEditor.from_file() reads the pristine original,
+        # not the mutated Pydantic model. Falls back to the canonical
+        # Pydantic rewrite (unchanged, below) on ANY failure -- a raised
+        # exception during recording, a compile-time error (e.g. an
+        # object-property Remove, which never happens here since every
+        # surgical_ops path is an array-element path), or a semantic
+        # validation failure (R3-7c).
+        surgical_succeeded = False
+        if surgical_ops:
+            try:
+                from json_source_edit import JSONEditor
+
+                editor = JSONEditor.from_file(tour_path)
+                for op in surgical_ops:
+                    if op[0] == "replace":
+                        editor.replace(op[1], op[2])
+                    else:
+                        editor.remove(op[1])
+                surgical_result = editor.save(tour_path, validate=True)
+                surgical_succeeded = surgical_result["success"]
+                if surgical_succeeded:
+                    log.info(
+                        "surgical_edit_succeeded",
+                        modifications=len(surgical_ops),
+                        tour=review.tour_name,
+                    )
+                else:
+                    log.warning(
+                        "surgical_edit_failed",
+                        error=surgical_result.get("error"),
+                        fallback="full_rewrite",
+                        tour=review.tour_name,
+                    )
+            except Exception as e:  # noqa: BLE001 -- deliberately broad: any
+                # surgical-path failure falls back to the full rewrite below,
+                # per the ADR's own fallback strategy.
+                log.warning(
+                    "surgical_edit_failed",
+                    error=str(e),
+                    fallback="full_rewrite",
+                    tour=review.tour_name,
+                )
+                surgical_succeeded = False
+
+        if not surgical_succeeded:
+            tour.save(tour_path)
+
+        # Build summary message
+        summary_parts = []
+        if applied_updates > 0:
+            summary_parts.append(f"{applied_updates} location update{'s' if applied_updates != 1 else ''}")
+        if applied_descriptions > 0:
+            summary_parts.append(f"{applied_descriptions} description edit{'s' if applied_descriptions != 1 else ''}")
+        if applied_deletions > 0:
+            summary_parts.append(f"{applied_deletions} deletion{'s' if applied_deletions != 1 else ''}")
+
+        summary = ", ".join(summary_parts)
+        print(f"\n✓ Applied {summary} to {review.tour_name}")
+
+        print("\nNext steps:")
+        print("  git diff .tours/")
+        print("  git add .tours/")
+        print('  git commit -m "chore: apply migration review corrections"')
+
+        return 0
+
+    except Exception as e:
+        print(f"❌ Failed to save tour: {e}", file=sys.stderr)
+        return 2
+
+
+def interactive_select_tours(tour_infos: list) -> list:
+    """
+    Interactive menu to select tours for migration.
+
+    Args:
+        tour_infos: List of TourInfo objects that need migration
+
+    Returns:
+        List of selected TourInfo objects, or empty list if user cancels
+    """
+    print("📊 Which tours do you want to migrate?\n")
+
+    # Show numbered list
+    for i, tour_info in enumerate(tour_infos, 1):
+        tour_name = tour_info.path.name
+        commits_behind = tour_info.commits_behind
+        print(f"  [{i}] {tour_name} ({commits_behind} commit{'s' if commits_behind != 1 else ''} behind)")
+
+    print(f"  [a] All tours")
+    print(f"  [q] Quit\n")
+
+    # Get user input
+    while True:
+        try:
+            choice = input("Enter number(s), 'a' for all, or 'q' to quit: ").strip().lower()
+
+            if choice == 'q':
+                return []
+
+            if choice == 'a':
+                return tour_infos
+
+            # Parse comma-separated numbers
+            indices = []
+            for part in choice.split(','):
+                part = part.strip()
+                if part.isdigit():
+                    idx = int(part) - 1
+                    if 0 <= idx < len(tour_infos):
+                        indices.append(idx)
+                    else:
+                        print(f"Invalid number: {part}")
+                        break
+                else:
+                    print(f"Invalid input: {part}")
+                    break
+            else:
+                # All parts valid
+                if indices:
+                    return [tour_infos[i] for i in indices]
+                print("No valid tours selected. Try again.")
+        except (EOFError, KeyboardInterrupt):
+            print("\nCancelled.")
+            return []
+
+
+def migrate_command(args, config: dict) -> int:
+    """
+    Execute the migrate command.
+
+    Migrates either a specific tour (if tour_file provided) or all out-of-date
+    tours (if no tour_file).
+
+    Returns:
+        Exit code (0 = success, 1 = needs review, 2 = error)
+    """
+    # If no tour file specified, migrate all out-of-date tours
+    if args.tour_file is None:
+        return migrate_all_tours(args, config)
+
+    # Migrate specific tour
+    return migrate_single_tour(args, config)
+
+
+def migrate_all_tours(args, config: dict) -> int:
+    """
+    Migrate all out-of-date tours in the repository.
+
+    Returns:
+        Exit code (0 = success, 1 = needs review, 2 = error)
+    """
+    # Warn if no config file
+    try:
+        repo_root = find_repo_root()
+        config_path = repo_root / "codetour.yaml"
+        if not config_path.exists():
+            print("ℹ️  No configuration file found. Run 'codetour-cli init' to create one.")
+            print()
+    except:
+        pass  # If we can't find repo, discover_repository will fail below
+
+    try:
+        # Discover tours
+        repo_info = discover_repository()
+    except (InvalidGitRepositoryError, ValueError) as e:
+        print(f"❌ {e}", file=sys.stderr)
+        return 2
+
+    # Find tours that need updating
+    out_of_date_tours = [
+        tour_info for tour_info in repo_info.tours
+        if not is_tour_up_to_date(tour_info)
+    ]
+
+    if not out_of_date_tours:
+        print("✓ All tours are up to date!")
+        return 0
+
+    # Interactive mode: let user select tours
+    if args.interactive:
+        selected_tours = interactive_select_tours(out_of_date_tours)
+        if not selected_tours:
+            print("No tours selected.")
+            return 0
+        out_of_date_tours = selected_tours
+
+    # Check for dry-run mode
+    is_dry_run = args.dry_run if hasattr(args, 'dry_run') else False
+
+    if is_dry_run:
+        print(f"🔍 DRY RUN: Previewing {len(out_of_date_tours)} tour{'s' if len(out_of_date_tours) != 1 else ''}\n")
+        print("ℹ️  No files will be modified. This is a preview only.\n")
+    else:
+        print(f"🔍 Found {len(out_of_date_tours)} tour{'s' if len(out_of_date_tours) != 1 else ''} needing migration\n")
+
+    # Merge config with command-line args
+    diff_algorithm = config.get("migration", {}).get("diff_algorithm", "histogram")
+    save_backup = not args.no_backup if hasattr(args, 'no_backup') else config.get("migration", {}).get("backup", True)
+    threshold = (
+        args.threshold if getattr(args, 'threshold', None) is not None
+        else config.get("migration", {}).get("threshold", 0.7)
+    )  # ADR-0016 QST-CONF-2 -- previously computed for display text only, never passed to the engine
+
+    # Migrate each tour
+    total_updated = 0
+    total_needs_review = 0
+    total_deprecated = 0
+    failed_tours = []
+    review_reports = []  # Track generated review reports
+
+    for tour_info in out_of_date_tours:
+        tour_name = tour_info.path.name
+        action_verb = "Analyzing" if is_dry_run else "Migrating"
+        print(f"{action_verb} {tour_name}...")
+
+        try:
+            result = update_tour_file(
+                repo_path=repo_info.repo_path,
+                tour_file=tour_info.path,
+                target_commit=args.to_commit,
+                source_commit=args.from_commit or tour_info.source_commit,
+                diff_algorithm=diff_algorithm,
+                save_backup=save_backup,
+                dry_run=is_dry_run,
+                threshold=threshold
+            )
+
+            total_updated += result.num_updated
+            total_needs_review += result.num_needs_review
+            total_deprecated += result.num_deprecated
+
+            # Brief summary per tour
+            verb_updated = "would be updated" if is_dry_run else "updated"
+            verb_need = "would need" if is_dry_run else "need"
+            print(f"  ✓ {result.num_updated} steps {verb_updated}")
+            if result.num_needs_review > 0:
+                print(f"  ⚠  {result.num_needs_review} steps {verb_need} review")
+
+            # Show detailed migration summary
+            print_migration_summary(result, tour_name, is_dry_run)
+
+            # Generate review report if needed
+            if result.num_needs_review > 0:
+                report_path = generate_review_report(
+                    tour_path=tour_info.path,
+                    result=result,
+                    source_commit=args.from_commit or tour_info.source_commit,
+                    target_commit=args.to_commit,
+                    repo_root=repo_info.repo_path,
+                    is_dry_run=is_dry_run,
+                    no_guidance=getattr(args, 'no_guidance', False),
+                    threshold=threshold
+                )
+                if report_path:
+                    review_reports.append(report_path)
+                    if is_dry_run:
+                        print(f"  📄 Review report generated (despite dry-run): {report_path.relative_to(repo_info.repo_path)}")
+                    else:
+                        print(f"  📄 Review report: {report_path.relative_to(repo_info.repo_path)}")
+
+        except Exception as e:
+            log.error("migration_failed", tour=tour_name, error=str(e))
+            print(f"  ❌ Failed: {e}\n")
+            failed_tours.append(tour_name)
+
+    # Overall summary
+    print("─" * 50)
+    if is_dry_run:
+        print(f"Dry Run Summary: Analyzed {len(out_of_date_tours)}/{len(out_of_date_tours)} tours")
+        print(f"  • {total_updated} steps would be updated")
+        if total_needs_review > 0:
+            print(f"  ⚠  {total_needs_review} steps would need review")
+        if total_deprecated > 0:
+            print(f"  ⚠  {total_deprecated} steps reference deleted files")
+        if failed_tours:
+            print(f"  ❌ {len(failed_tours)} tours failed to analyze")
+        print()
+        print("To apply these changes:")
+
+        # Build accurate command suggestion based on what was previewed
+        if len(out_of_date_tours) == 1:
+            # Single tour - show both specific file and interactive options
+            tour_file = out_of_date_tours[0].path
+            print(f"  • Migrate this specific tour directly:")
+            print(f"    codetour-cli migrate {tour_file}")
+            print(f"  • Or use interactive mode:")
+            print(f"    codetour-cli migrate --interactive")
+        elif args.interactive:
+            # Multiple tours with interactive - suggest interactive mode and specific files
+            print(f"  • Run 'codetour-cli migrate --interactive' and select the same tours")
+            print(f"  • Or migrate specific tours directly:")
+            for tour_info in out_of_date_tours[:3]:  # Show first 3
+                print(f"    - codetour-cli migrate {tour_info.path}")
+            if len(out_of_date_tours) > 3:
+                print(f"    ... and {len(out_of_date_tours) - 3} more")
+        else:
+            # Multiple tours without interactive - list them or suggest batch
+            if len(out_of_date_tours) <= 3:
+                # Few tours - list them with bullet points
+                print(f"  • Migrate specific tours:")
+                for tour_info in out_of_date_tours:
+                    print(f"    - codetour-cli migrate {tour_info.path}")
+            else:
+                # Many tours - suggest batch or interactive
+                print(f"  • Migrate all tours:")
+                print(f"    codetour-cli migrate")
+                print(f"  • Or use interactive mode to select:")
+                print(f"    codetour-cli migrate --interactive")
+    else:
+        print(f"Summary: Migrated {len(out_of_date_tours) - len(failed_tours)}/{len(out_of_date_tours)} tours")
+        print(f"  • {total_updated} steps updated")
+        if total_needs_review > 0:
+            print(f"  ⚠  {total_needs_review} steps need review")
+        if total_deprecated > 0:
+            print(f"  ⚠  {total_deprecated} steps reference deleted files")
+        if failed_tours:
+            print(f"  ❌ {len(failed_tours)} tours failed")
+
+        print()
+        if review_reports:
+            print(f"📋 Review reports generated:")
+            for report_path in review_reports:
+                print(f"  • {report_path.relative_to(repo_info.repo_path)}")
+            print()
+        _post_migration_lint(
+            [t.path for t in out_of_date_tours],
+            config,
+            no_lint=getattr(args, 'no_lint', False),
+            dry_run=False,
+            repo_root=repo_info.repo_path,
+        )
+        print("Next steps:")
+        print("  git diff .tours/")
+        print("  git add .tours/")
+        print('  git commit -m "chore: update tours to current HEAD"')
+
+    # Exit code
+    if failed_tours:
+        return 2
+    elif total_needs_review > 0 or total_deprecated > 0:
+        return 1
+    else:
+        return 0
+
+
+def migrate_single_tour(args, config: dict) -> int:
+    """
+    Migrate a single specified tour file.
+
+    Returns:
+        Exit code (0 = success, 1 = needs review, 2 = error)
+    """
+    tour_path = Path(args.tour_file)
+
+    # Verify tour file exists
+    if not tour_path.exists():
+        print(f"❌ Tour file not found: {tour_path}", file=sys.stderr)
+        return 2
+
+    # Check Git exists
+    try:
+        repo = Repo('.', search_parent_directories=True)
+    except InvalidGitRepositoryError:
+        print("❌ CodeTour CLI requires Git to track tour drift.", file=sys.stderr)
+        print(file=sys.stderr)
+        print("This repository is not a Git repository.", file=sys.stderr)
+        print(file=sys.stderr)
+        print("To enable tour maintenance:", file=sys.stderr)
+        print("  git init", file=sys.stderr)
+        print("  git add .", file=sys.stderr)
+        print('  git commit -m "Initial commit"', file=sys.stderr)
+        print(file=sys.stderr)
+        print("Then re-run: codetour-cli migrate", file=sys.stderr)
+        return 2
+
+    # Detect or use override for source commit
+    if args.from_commit:
+        source_commit = args.from_commit
+        log.info("using_override", commit=source_commit[:8] if len(source_commit) >= 8 else source_commit)
+        print(f"ℹ Using override source commit: {source_commit[:8]}...")
+    else:
+        # Make tour_path relative to repo root for git operations
+        try:
+            tour_path_rel = tour_path.relative_to(repo.working_dir)
+        except ValueError:
+            # If path is already relative or outside repo, use as-is
+            tour_path_rel = tour_path
+
+        source_commit, confidence, method = detect_source_commit(repo, tour_path_rel)
+
+        print(f"ℹ Detected source commit: {source_commit[:8]}... (confidence: {confidence:.0%}, method: {method})")
+
+    # Merge config with command-line args
+    diff_algorithm = config.get("migration", {}).get("diff_algorithm", "histogram")
+    save_backup = not args.no_backup if hasattr(args, 'no_backup') else config.get("migration", {}).get("backup", True)
+    threshold = (
+        args.threshold if getattr(args, 'threshold', None) is not None
+        else config.get("migration", {}).get("threshold", 0.7)
+    )  # ADR-0016 QST-CONF-2 -- previously computed for display text only, never passed to the engine
+    is_dry_run = args.dry_run if hasattr(args, 'dry_run') else False
+
+    if is_dry_run:
+        print("\nℹ️  DRY RUN: No files will be modified. This is a preview only.\n")
+
+    # Run migration
+    try:
+        result = update_tour_file(
+            repo_path=repo.working_dir,
+            tour_file=tour_path,
+            target_commit=args.to_commit,
+            source_commit=source_commit,
+            diff_algorithm=diff_algorithm,
+            save_backup=save_backup,
+            dry_run=is_dry_run,
+            threshold=threshold
+        )
+    except Exception as e:
+        log.error("migration_failed", error=str(e))
+        print(f"❌ Migration failed: {e}", file=sys.stderr)
+        return 2
+
+    # Report results
+    print()
+    if is_dry_run:
+        print(f"✓ Would migrate {result.num_updated} steps")
+    else:
+        print(f"✓ Migrated {result.num_updated} steps")
+
+    if result.num_needs_review > 0:
+        verb = "would need" if is_dry_run else "need"
+        print(f"⚠ {result.num_needs_review} steps {verb} review (confidence < 0.7)")
+
+    if result.num_deprecated > 0:
+        print(f"⚠ {result.num_deprecated} steps reference deleted files")
+
+    # Show detailed migration summary
+    print_migration_summary(result, tour_path.name, is_dry_run)
+
+    # Generate review report if needed
+    if result.num_needs_review > 0:
+        report_path = generate_review_report(
+            tour_path=tour_path,
+            result=result,
+            source_commit=source_commit,
+            target_commit=args.to_commit,
+            repo_root=Path(repo.working_dir),
+            is_dry_run=is_dry_run,
+            no_guidance=getattr(args, 'no_guidance', False),
+            threshold=threshold
+        )
+        if report_path:
+            if is_dry_run:
+                print(f"\n  📄 Review report generated (despite dry-run): {report_path.relative_to(repo.working_dir)}")
+            else:
+                print(f"\n  📄 Review report: {report_path.relative_to(repo.working_dir)}")
+
+    if is_dry_run:
+        print("\nTo apply these changes, run:")
+        print(f"  codetour-cli migrate {tour_path}")
+        print()
+
+    _post_migration_lint(
+        [tour_path],
+        config,
+        no_lint=getattr(args, 'no_lint', False),
+        dry_run=is_dry_run,
+        repo_root=Path(repo.working_dir),
+    )
+
+    # Determine exit code
+    if result.num_needs_review > 0 or result.num_deprecated > 0:
+        return 1  # Needs review
+    else:
+        return 0  # Success
+
+
+if __name__ == '__main__':
+    sys.exit(main())