agentic-devtools 0.2.31__tar.gz → 0.2.33__tar.gz

{agentic_devtools-0.2.31 → agentic_devtools-0.2.33}/.github/copilot-instructions.md

@@ -1505,7 +1505,18 @@ agdt-initiate-pull-request-review-workflow --pull-request-id 12345 --interactive
 3. Validates the current worktree/branch context via pre-flight checks.
 4. If the context is wrong, **automatically creates a dedicated worktree**, attempts to open VS Code (when available), then re-runs the command inside the new worktree.
 5. Fetches full PR details (diff, threads, iterations) and Jira issue details.
-6. Generates per-file review prompts in `pull-request-review/prompts/<pr_id>/` under the state directory.
+6. Generates per-file review prompts in `pull-request-review/<commit_hash_short>/` under the state directory.
+
+    > **⚠️ Migration note (upgrading from pre-refactor versions):**
+    > The artifact directory layout changed from `pull-request-review/prompts/<pr_id>/` to
+    > `pull-request-review/<commit_hash_short>/` in this release.
+    > `_get_queue_path` transparently falls back to the legacy path when the new path's
+    > `queue.json` is absent but the old one exists, so **in-progress reviews continue to
+    > work after upgrade without any manual migration**.  Once a new review session is
+    > started (via `agdt-review-pull-request`), artifacts for that PR will be written to
+    > the new path.  Artifacts from the old path can be safely deleted after all active
+    > reviews complete.
+
 7. **When auto-setup ran (new worktree was created):** starts a `gh copilot` CLI session
    (interactive or background depending on `--interactive`). When already in the correct
    worktree context, the rendered initiate prompt is printed to the console for the agent
@@ -1570,7 +1581,7 @@ reviewed.
 
 #### Review State File (`review-state.json`)
 
-Location: `.agdt/workflows/{identity}/{worktree_key}/pull-request-review/prompts/{pr_id}/review-state.json`
+Location: `<state_dir>/reviews/review-state.json` (where `<state_dir>` is `.agdt/workflows/{identity}/{worktree_key}`)
 
 This file tracks all thread IDs, statuses, and suggestions for the entire review session:
 
@@ -1824,8 +1835,8 @@ agdt-add-jira-comment  # Previews without posting
 | `.agdt/workflows/…/state.json` | All commands | Persistent state storage |
 | `.agdt/workflows/…/temp-get-issue-details-response.json` | `agdt-get-jira-issue` | Full Jira API response |
 | `.agdt/workflows/…/temp-get-pull-request-details-response.json` | `agdt-get-pull-request-details` | Full PR details payload |
-| `.agdt/workflows/…/pull-request-review/prompts/<pr_id>/` | `agdt-review-pull-request` | Review prompts directory |
-| `.agdt/workflows/…/pull-request-review/prompts/<pr_id>/review-state.json` | `agdt-review-pull-request` | Hierarchical review state (thread IDs, statuses, suggestions) |
+| `.agdt/workflows/…/pull-request-review/<commit_hash_short>/` | `agdt-review-pull-request` | Review prompts directory |
+| `.agdt/workflows/…/reviews/review-state.json` | `agdt-review-pull-request` | Hierarchical review state (thread IDs, statuses, suggestions) |
 | `.agdt/workflows/…/temp-<workflow>-<step>-prompt.md` | Workflow initiation commands | Rendered workflow prompts |
 
 ### Background Task Storage Structure

{agentic_devtools-0.2.31 → agentic_devtools-0.2.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-devtools
-Version: 0.2.31
+Version: 0.2.33
 Summary: AI assistant helper commands for the Dragonfly platform
 Author: Dragonfly Team
 License-Expression: MIT
@@ -462,6 +462,34 @@ NOTE: VS Code integrated terminal auto-start not available. Copilot session
 will run in the background. Run agdt-task-log to view output.
 ```
 
+### Automated Copilot Session Launch
+
+All `agdt-initiate-*-workflow` commands automatically launch a Copilot CLI session after
+workflow initiation (and auto-setup when needed). The rendered prompt is saved to the
+workflow state directory; the session starts with a short **bootstrap prompt** that
+instructs the agent to run the first workflow command. For most workflows this is
+`agdt-get-next-workflow-prompt`; for the PR review workflow it is
+`agdt-advance-workflow pull-request-overview`. See
+[`docs/workflow-prompts.md`](docs/workflow-prompts.md) for the prompt file inventory and
+full lifecycle.
+
+Two session modes exist depending on context. When a new worktree is opened in VS Code, a
+`folderOpen` auto-start task starts an interactive session in the integrated terminal
+regardless of `--interactive`. For direct invocations from the CLI, pass
+`--interactive true` to attach to the terminal (requires a TTY and VS Code), or omit it
+(default: non-interactive) to run the Copilot session as a detached background process
+(not an agdt background task — use the `copilot.*` state keys to locate the session log
+file):
+
+```bash
+agdt-initiate-work-on-jira-issue-workflow --issue-key DFLY-1234
+agdt-initiate-pull-request-review-workflow --pull-request-id 12345 --interactive true
+```
+
+If auto-session launch fails (no `gh copilot`, no TTY, or VS Code unavailable), the
+rendered prompt is printed to the console and saved to the workflow state directory so you
+can paste it manually into Copilot Chat as a fallback.
+
 ### Work on Jira Issue Workflow
 
 ```bash

{agentic_devtools-0.2.31 → agentic_devtools-0.2.33}/README.md

@@ -436,6 +436,34 @@ NOTE: VS Code integrated terminal auto-start not available. Copilot session
 will run in the background. Run agdt-task-log to view output.
 ```
 
+### Automated Copilot Session Launch
+
+All `agdt-initiate-*-workflow` commands automatically launch a Copilot CLI session after
+workflow initiation (and auto-setup when needed). The rendered prompt is saved to the
+workflow state directory; the session starts with a short **bootstrap prompt** that
+instructs the agent to run the first workflow command. For most workflows this is
+`agdt-get-next-workflow-prompt`; for the PR review workflow it is
+`agdt-advance-workflow pull-request-overview`. See
+[`docs/workflow-prompts.md`](docs/workflow-prompts.md) for the prompt file inventory and
+full lifecycle.
+
+Two session modes exist depending on context. When a new worktree is opened in VS Code, a
+`folderOpen` auto-start task starts an interactive session in the integrated terminal
+regardless of `--interactive`. For direct invocations from the CLI, pass
+`--interactive true` to attach to the terminal (requires a TTY and VS Code), or omit it
+(default: non-interactive) to run the Copilot session as a detached background process
+(not an agdt background task — use the `copilot.*` state keys to locate the session log
+file):
+
+```bash
+agdt-initiate-work-on-jira-issue-workflow --issue-key DFLY-1234
+agdt-initiate-pull-request-review-workflow --pull-request-id 12345 --interactive true
+```
+
+If auto-session launch fails (no `gh copilot`, no TTY, or VS Code unavailable), the
+rendered prompt is printed to the console and saved to the workflow state directory so you
+can paste it manually into Copilot Chat as a fallback.
+
 ### Work on Jira Issue Workflow
 
 ```bash

{agentic_devtools-0.2.31 → agentic_devtools-0.2.33}/agentic_devtools/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.31'
-__version_tuple__ = version_tuple = (0, 2, 31)
+__version__ = version = '0.2.33'
+__version_tuple__ = version_tuple = (0, 2, 33)
 
 __commit_id__ = commit_id = None

{agentic_devtools-0.2.31 → agentic_devtools-0.2.33}/agentic_devtools/agdt_gitignore.py

@@ -13,7 +13,7 @@ from typing import Optional
 # Paths (relative to .agdt/) that must be git-ignored on code branches.
 # Used both for writing .agdt/.gitignore and for defense-in-depth unstaging
 # in stage_changes().
-AGDT_GITIGNORE_ENTRIES = ("runtime-bootstrap.json", "workflows/")
+AGDT_GITIGNORE_ENTRIES = ("runtime-bootstrap.json", "identity.json", "workflows/")
 
 AGDT_GITIGNORE_HEADER = (
     "# Managed by agentic-devtools — do not edit manually.\n"

{agentic_devtools-0.2.31 → agentic_devtools-0.2.33}/agentic_devtools/cli/azure_devops/file_review_commands.py

@@ -13,14 +13,23 @@ import json
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
+from typing import TYPE_CHECKING, Dict, Optional
 
 from ...state import get_pull_request_id, get_state_dir, get_value, is_dry_run
 from .auth import get_auth_headers, get_pat
 from .config import AzureDevOpsConfig
-from .helpers import get_repository_id, patch_comment, patch_thread_status, require_requests
+from .helpers import (
+    get_repository_id,
+    patch_comment,
+    patch_thread_status,
+    require_requests,
+    resolve_review_artifact_dir_name,
+)
 from .mark_reviewed import mark_file_reviewed
 
+if TYPE_CHECKING:
+    from .review_state import ReviewState
+
 
 def _normalize_repo_path(path: Optional[str]) -> Optional[str]:
     """Normalize a file path to repository format (/path/to/file)."""
@@ -32,6 +41,65 @@ def _normalize_repo_path(path: Optional[str]) -> Optional[str]:
     return f"/{clean}"
 
 
+def _get_attribution_params(
+    review_state: "ReviewState",
+    config: AzureDevOpsConfig,
+    file_path: Optional[str] = None,
+) -> Dict[str, Optional[str]]:
+    """Extract attribution parameters from ReviewState for comment rendering.
+
+    Returns a dict with keys ``model_name``, ``commit_hash``, and ``commit_url``
+    that can be unpacked as keyword arguments into ``render_file_summary()`` and
+    ``render_overall_summary()``.  Any value may be ``None`` when the required
+    data is absent (e.g. no sessions recorded, no commit hash stored yet).
+
+    Args:
+        review_state: Current ReviewState instance.
+        config: AzureDevOpsConfig with org/project/repository.
+        file_path: Optional file path for per-file URL (overall PR URL used when absent).
+
+    Returns:
+        Dict with ``model_name``, ``commit_hash``, and ``commit_url``.
+    """
+    from .review_attribution import build_commit_file_url, build_commit_pr_url
+    from .review_state import normalize_file_path
+
+    # Prefer the latest session model ID when available, but fall back to the
+    # top-level ReviewState.modelId for backward/partial states where sessions
+    # may be empty while the model is still known.
+    model_name: Optional[str]
+    if getattr(review_state, "sessions", None):
+        model_name = review_state.sessions[-1].modelId
+    else:
+        model_name = getattr(review_state, "modelId", None)
+
+    commit_hash = review_state.commitHash
+    commit_url: Optional[str] = None
+    if commit_hash and review_state.latestIterationId:
+        try:
+            if file_path:
+                normalized = normalize_file_path(file_path)
+                commit_url = build_commit_file_url(
+                    config.organization,
+                    config.project,
+                    config.repository,
+                    review_state.prId,
+                    normalized,
+                    review_state.latestIterationId,
+                )
+            else:
+                commit_url = build_commit_pr_url(
+                    config.organization,
+                    config.project,
+                    config.repository,
+                    review_state.prId,
+                    review_state.latestIterationId,
+                )
+        except Exception:
+            commit_url = None
+    return {"model_name": model_name, "commit_hash": commit_hash, "commit_url": commit_url}
+
+
 def _get_thread_file_path(thread: dict) -> Optional[str]:
     """Extract the file path from a thread's context."""
     context = thread.get("threadContext")
@@ -55,8 +123,30 @@ def _get_thread_file_path(thread: dict) -> Optional[str]:
 
 
 def _get_queue_path(pull_request_id: int) -> Path:
-    """Get the path to the queue.json file for a pull request."""
-    return get_state_dir() / "pull-request-review" / "prompts" / str(pull_request_id) / "queue.json"
+    """Get the path to the queue.json file for a pull request.
+
+    Returns the new commit-hash-scoped path
+    (``pull-request-review/<dir_name>/queue.json``).  If that file does not yet
+    exist but the legacy path (``pull-request-review/prompts/<pr_id>/queue.json``)
+    does, the legacy path is returned instead so that in-progress review sessions
+    created before the commit-hash-short refactor continue to work transparently
+    after an upgrade.
+    """
+    commit_hash_short = get_value("review.commit_hash_short")
+    # Suppress warnings here: this function is called many times per review command.
+    # Warnings about a missing/unsafe commit hash are more useful at setup time
+    # (generate_review_prompts / checkout_and_sync_branch) than repeated per queue op.
+    dir_name = resolve_review_artifact_dir_name(pull_request_id, commit_hash_short, warn=False)
+    state_dir = get_state_dir()
+    new_path = state_dir / "pull-request-review" / dir_name / "queue.json"
+    # Backward-compatible fallback: silently use the legacy path when the new one
+    # is absent but an old-format queue still exists.  This prevents silent queue
+    # loss (empty/default status) when upgrading mid-review.
+    if not new_path.exists():
+        legacy_path = state_dir / "pull-request-review" / "prompts" / str(pull_request_id) / "queue.json"
+        if legacy_path.exists():
+            return legacy_path
+    return new_path
 
 
 def mark_file_as_submission_pending(
@@ -481,7 +571,18 @@ def trigger_in_progress_for_file(
         auth_headers = get_auth_headers(get_pat())
 
     # PATCH file summary comment content; file thread status stays "active" per spec
-    file_content = render_file_summary(file_entry, file_entry.suggestions, base_url)
+    attrs = _get_attribution_params(review_state, config, file_path=file_path)
+
+    # Ensure the current model's verdict reflects that review is in progress.
+    # attrs["model_name"] holds the model ID derived from the review session.
+    model_id = attrs.get("model_name")
+    if model_id is not None:
+        current_verdict = file_entry.get_model_verdict(model_id)
+        if current_verdict is not None:
+            current_verdict.status = ReviewStatus.IN_PROGRESS.value
+            current_verdict.verdictType = None
+
+    file_content = render_file_summary(file_entry, file_entry.suggestions, base_url, **attrs)
     patch_comment(
         requests_module=requests_module,
         headers=auth_headers,
@@ -498,7 +599,8 @@ def trigger_in_progress_for_file(
     # review_state even if downstream cascade execution fails, so the
     # local state reflects the already-PATCHed file comment.
     try:
-        ops = cascade_status_update(review_state, file_path, base_url)
+        cascade_attrs = _get_attribution_params(review_state, config)
+        ops = cascade_status_update(review_state, file_path, base_url, **cascade_attrs)
         execute_cascade(ops, requests_module, auth_headers, config, repo_id, pull_request_id, dry_run=dry_run)
     finally:
         if not dry_run:
@@ -1029,8 +1131,20 @@ def approve_file() -> None:  # pragma: no cover
             )
             sys.exit(1)
 
+        # Record verdict for model progress table; skip when no model ID is known
+        # to avoid polluting the review state with a spurious "unknown" row.
+        from .verdict_protocol import VerdictType, record_verdict
+
+        if review_state.sessions:
+            model_id = review_state.sessions[-1].modelId
+        else:
+            model_id = getattr(review_state, "modelId", None)
+        if model_id:
+            record_verdict(file_entry, model_id, VerdictType.AGREE, ReviewStatus.APPROVED.value)
+
         # PATCH file summary comment with regenerated markdown
-        file_content = render_file_summary(file_entry, [], base_url)
+        attrs = _get_attribution_params(review_state, config, file_path=file_path)
+        file_content = render_file_summary(file_entry, [], base_url, **attrs)
         patch_comment(
             requests_module=requests,
             headers=headers,
@@ -1068,7 +1182,8 @@ def approve_file() -> None:  # pragma: no cover
         # review_state even if downstream cascade execution fails, so the
         # local state reflects the already-PATCHed file comment.
         try:
-            patch_operations = cascade_status_update(review_state, file_path, base_url)
+            cascade_attrs = _get_attribution_params(review_state, config)
+            patch_operations = cascade_status_update(review_state, file_path, base_url, **cascade_attrs)
             execute_cascade(
                 patch_operations=patch_operations,
                 requests_module=requests,
@@ -1543,8 +1658,20 @@ def request_changes() -> None:
 
             file_entry = review_state.files[normalized]
 
+            # Record verdict for model progress table; skip when no model ID is known
+            # to avoid polluting the review state with a spurious "unknown" row.
+            from .verdict_protocol import VerdictType, record_verdict
+
+            if review_state.sessions:
+                model_id = review_state.sessions[-1].modelId
+            else:
+                model_id = getattr(review_state, "modelId", None)
+            if model_id:
+                record_verdict(file_entry, model_id, VerdictType.AGREE, ReviewStatus.NEEDS_WORK.value)
+
             # PATCH file summary comment with regenerated markdown
-            file_content = render_file_summary(file_entry, file_entry.suggestions, base_url)
+            attrs = _get_attribution_params(review_state, config, file_path=file_path)
+            file_content = render_file_summary(file_entry, file_entry.suggestions, base_url, **attrs)
             patch_comment(
                 requests_module=requests,
                 headers=headers,
@@ -1579,7 +1706,8 @@ def request_changes() -> None:
             )
 
             # Cascade folder and overall summary updates
-            patch_operations = cascade_status_update(review_state, file_path, base_url)
+            cascade_attrs = _get_attribution_params(review_state, config)
+            patch_operations = cascade_status_update(review_state, file_path, base_url, **cascade_attrs)
             execute_cascade(
                 patch_operations=patch_operations,
                 requests_module=requests,

{agentic_devtools-0.2.31 → agentic_devtools-0.2.33}/agentic_devtools/cli/azure_devops/helpers.py

@@ -6,11 +6,13 @@ Pure utility functions that don't read state directly.
 
 import json
 import re
+import reprlib
 import subprocess
 import sys
 import time
 from typing import Any, Dict, List, Optional
 
+from ...state import is_safe_dir_segment
 from ..subprocess_utils import run_safe
 from .config import (
     DEFAULT_ORGANIZATION,
@@ -647,3 +649,64 @@ def find_pr_from_jira_issue(
         pass
 
     return None
+
+
+def resolve_review_artifact_dir_name(pull_request_id: int, commit_hash_short: Any | None, warn: bool = True) -> str:
+    """Return a safe, ``str``-typed directory-name segment for scoping review artifacts.
+
+    Reads *commit_hash_short* (already retrieved from state by the caller) and
+    validates it with :func:`is_safe_dir_segment`.  Falls back to
+    ``'PR<pull_request_id>'`` (printing a warning to stderr when *warn* is
+    ``True``) when the value is absent, not a safe path segment, or cannot be
+    coerced to a plain ``str``.
+
+    Pass ``warn=False`` from high-frequency callers (e.g. ``_get_queue_path``)
+    to avoid spamming stderr on every queue operation when the key is absent.
+
+    The returned value is always a plain :class:`str`, safe for direct use as a
+    single :class:`pathlib.Path` segment without further coercion or validation.
+    """
+    fallback = f"PR{pull_request_id}"
+
+    def _safe_repr(obj: Any) -> str:
+        """Return a bounded, exception-safe repr for use in warning paths."""
+        try:
+            return reprlib.repr(obj)
+        except Exception:
+            return f"<unrepr:{type(obj).__name__}>"
+
+    if commit_hash_short is None or commit_hash_short == "":
+        if warn:
+            print(
+                f"Warning: review.commit_hash_short not set; using {fallback!r} as artifact directory.",
+                file=sys.stderr,
+            )
+        return fallback
+    try:
+        as_str = str(commit_hash_short).strip()
+    except Exception:
+        if warn:
+            print(
+                "Warning: review.commit_hash_short "
+                f"{_safe_repr(commit_hash_short)} could not be coerced to str; "
+                f"using {fallback!r} as artifact directory.",
+                file=sys.stderr,
+            )
+        return fallback
+    if as_str == "":
+        if warn:
+            print(
+                f"Warning: review.commit_hash_short not set; using {fallback!r} as artifact directory.",
+                file=sys.stderr,
+            )
+        return fallback
+    if not is_safe_dir_segment(as_str):
+        if warn:
+            print(
+                "Warning: review.commit_hash_short "
+                f"{_safe_repr(commit_hash_short)} is unsafe; "
+                f"using {fallback!r} as artifact directory.",
+                file=sys.stderr,
+            )
+        return fallback
+    return as_str

{agentic_devtools-0.2.31 → agentic_devtools-0.2.33}/agentic_devtools/cli/azure_devops/pull_request_details_commands.py

@@ -443,7 +443,6 @@ def get_pull_request_details() -> None:
 
     Output:
         - Writes JSON to temp-get-pull-request-details-response.json in the state directory
-        - Writes file details to pull-request-review/prompts/<pull_request_id>/pull-request-files.json
 
     Raises:
         SystemExit: On validation or execution errors.
@@ -455,11 +454,9 @@ def get_pull_request_details() -> None:
     # Determine output paths
     temp_dir = get_state_dir()
     output_file = temp_dir / "temp-get-pull-request-details-response.json"
-    prompts_root = temp_dir / "pull-request-review" / "prompts"
 
-    # Ensure directories exist
+    # Ensure state directory exists
     temp_dir.mkdir(parents=True, exist_ok=True)
-    prompts_root.mkdir(parents=True, exist_ok=True)
 
     if dry_run:
         print(f"DRY-RUN: Would retrieve pull request details for PR {pull_request_id}")
@@ -576,13 +573,6 @@ def get_pull_request_details() -> None:
         "compareBranch": source_branch,
     }
 
-    # Save files snapshot
-    pull_request_prompt_dir = prompts_root / str(pull_request_id)
-    pull_request_prompt_dir.mkdir(parents=True, exist_ok=True)
-    files_snapshot_path = pull_request_prompt_dir / "pull-request-files.json"
-    with open(files_snapshot_path, "w", encoding="utf-8") as f:
-        json.dump({"files": files_details}, f, indent=2)
-
     # Fetch threads, iterations, reviewer data
     repo_id = pr_data.get("repository", {}).get("id")
     project_id = pr_data.get("repository", {}).get("project", {}).get("id")

{agentic_devtools-0.2.31 → agentic_devtools-0.2.33}/agentic_devtools/cli/azure_devops/review_commands.py

@@ -10,11 +10,11 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, Optional, Set
 
-from ...state import get_state_dir, get_value, is_dry_run
+from ...state import get_state_dir, get_value, is_dry_run, is_safe_dir_segment
 from ..subprocess_utils import run_safe
 from .auth import get_auth_headers, get_pat
 from .config import AzureDevOpsConfig
-from .helpers import require_requests, verify_az_cli
+from .helpers import require_requests, resolve_review_artifact_dir_name, verify_az_cli
 
 # Import helper modules
 
@@ -212,8 +212,10 @@ def checkout_and_sync_branch(
 
     # Optionally save files_on_branch to JSON for async workflows
     if save_files_on_branch and pull_request_id:
+        commit_hash_short = get_value("review.commit_hash_short")
+        dir_name = resolve_review_artifact_dir_name(pull_request_id, commit_hash_short)
         temp_dir = get_state_dir()
-        prompts_dir = temp_dir / "pull-request-review" / "prompts" / str(pull_request_id)
+        prompts_dir = temp_dir / "pull-request-review" / dir_name
         prompts_dir.mkdir(parents=True, exist_ok=True)
         files_on_branch_path = prompts_dir / "files-on-branch.json"
         with open(files_on_branch_path, "w", encoding="utf-8") as f:
@@ -356,7 +358,9 @@ def generate_review_prompts(
     )
 
     temp_dir = get_state_dir()
-    prompts_dir = temp_dir / "pull-request-review" / "prompts" / str(pull_request_id)
+    commit_hash_short = get_value("review.commit_hash_short")
+    dir_name = resolve_review_artifact_dir_name(pull_request_id, commit_hash_short)
+    prompts_dir = temp_dir / "pull-request-review" / dir_name
     prompts_dir.mkdir(parents=True, exist_ok=True)
 
     # Load pr_details from temp file if not provided
@@ -623,8 +627,17 @@ def _scaffold_threads_for_review(
         iterations = pr_details.get("iterations") or []
         latest_iteration_id = max((it.get("id", 0) for it in iterations), default=0)
 
-        # Extract commit hash from PR info
-        commit_hash = pr_info.get("lastMergeSourceCommit", {}).get("commitId")
+        # Extract commit hash from PR info, guarding against JSON null → None or unexpected types
+        last_merge = pr_info.get("lastMergeSourceCommit")
+        commit_hash_raw = last_merge.get("commitId") if isinstance(last_merge, dict) else None
+        if commit_hash_raw is not None and not isinstance(commit_hash_raw, str):
+            print(
+                f"Warning: lastMergeSourceCommit.commitId has unexpected type "
+                f"{type(commit_hash_raw).__name__!r}; omitting from scaffolding.",
+                file=sys.stderr,
+            )
+            commit_hash_raw = None
+        commit_hash = commit_hash_raw
 
         # Resolve model_id from state; defaults to "unknown" if not set
         model_id = get_value("review.model_id") or "unknown"
@@ -680,6 +693,7 @@ def setup_pull_request_review() -> None:
     This function is designed to be called in a background task from the
     workflow initiation command.
     """
+    from ...state import delete_value, set_value
     from .pull_request_details_commands import get_pull_request_details
 
     # Read parameters from state
@@ -701,7 +715,7 @@ def setup_pull_request_review() -> None:
     try:
         import uuid
 
-        from ...state import set_bootstrap_state, set_value
+        from ...state import set_bootstrap_state
 
         set_bootstrap_state(worktree_key=f"PR{pull_request_id}")
 
@@ -755,6 +769,58 @@ def setup_pull_request_review() -> None:
 
     # Step 3: Checkout source branch and sync with main
     pr_info = pr_details.get("pullRequest", pr_details)
+
+    # Extract and store commit hash short for artifact directory scoping.
+    # This must be set before checkout_and_sync_branch() and generate_review_prompts()
+    # so that both use the correct directory under pull-request-review/.
+    # When commitId is absent, delete any stale value to keep artifact paths deterministic.
+    last_merge = pr_info.get("lastMergeSourceCommit")
+    if not isinstance(last_merge, dict):
+        if last_merge is not None:
+            print(
+                f"Warning: lastMergeSourceCommit has unexpected type "
+                f"{type(last_merge).__name__!r}; review artifacts will be scoped by PR ID.",
+                file=sys.stderr,
+            )
+        source_commit_id = ""
+    else:
+        source_commit_id = last_merge.get("commitId", "")
+        # Treat empty string as "absent", but warn and normalize any other non-string value.
+        if not isinstance(source_commit_id, str):
+            if source_commit_id != "":
+                print(
+                    f"Warning: lastMergeSourceCommit.commitId has unexpected type "
+                    f"{type(source_commit_id).__name__!r}; review artifacts will be scoped by PR ID.",
+                    file=sys.stderr,
+                )
+            source_commit_id = ""
+        else:
+            # Normalize leading/trailing whitespace so the derived short hash matches
+            # the canonical directory segment used for review artifacts.
+            normalized_commit_id = source_commit_id.strip()
+            if not normalized_commit_id:
+                # If the commit ID was empty or only whitespace, treat it as absent.
+                source_commit_id = ""
+            else:
+                source_commit_id = normalized_commit_id
+
+    commit_hash_short = ""
+    if source_commit_id:
+        commit_hash_short = source_commit_id[:8]
+        # Validate that commit_hash_short is safe to persist and use as a path segment.
+        if not is_safe_dir_segment(commit_hash_short):
+            print(
+                "Warning: Derived commit_hash_short contains unexpected characters; "
+                "review artifacts will be scoped by PR ID.",
+                file=sys.stderr,
+            )
+            commit_hash_short = ""
+
+    if commit_hash_short:
+        set_value("review.commit_hash_short", commit_hash_short)
+    else:
+        delete_value("review.commit_hash_short")
+
     source_branch = pr_info.get("sourceRefName", "").replace("refs/heads/", "")
 
     files_on_branch: Set[str] | None = None