agentic-devtools 0.2.18__tar.gz → 0.2.20__tar.gz

{agentic_devtools-0.2.18 → agentic_devtools-0.2.20}/.github/copilot-instructions.md

@@ -345,7 +345,7 @@ All action commands that mutate state or perform API calls spawn background task
 | `agdt-run-e2e-tests` | Trigger E2E test pipeline | (pipeline params) |
 | `agdt-run-wb-patch` | Trigger workbench patch pipeline | (pipeline params) |
 | `agdt-review-pull-request` | Start PR review workflow | (optional) pull_request_id, jira.issue_key |
-| `agdt-generate-pr-summary` | Generate PR summary comments | pull_request_id |
+| `agdt-generate-pr-summary` | ~~Generate PR summary comments~~ (**Deprecated** — summaries are now generated automatically by the PR review workflow after all file reviews complete, typically triggered via `agdt-task-wait`) | pull_request_id |
 
 **Create Pull Request CLI Parameter Support:**
 
@@ -373,9 +373,9 @@ Query commands also spawn background tasks - results are written to output files
 | Command | Purpose | Required State / CLI Args |
 |---------|---------|---------------------------|
 | `agdt-review-pull-request` | Start PR review workflow | (optional) pull_request_id or jira.issue_key |
-| `agdt-approve-file` | Approve a file during review | pull_request_id, file_review.file_path, content OR `--file-path`, `--content`, `--pull-request-id` |
-| `agdt-request-changes` | Request changes on a file | pull_request_id, file_review.file_path, content, line OR `--file-path`, `--content`, `--line`, `--pull-request-id` |
-| `agdt-request-changes-with-suggestion` | Request changes with code suggestion | pull_request_id, file_review.file_path, content, line OR `--file-path`, `--content`, `--line`, `--pull-request-id` |
+| `agdt-approve-file` | Approve a file during review | pull_request_id, file_review.file_path, file_review.summary OR `--file-path`, `--summary`, `--pull-request-id` |
+| `agdt-request-changes` | Request changes on a file | pull_request_id, file_review.file_path, file_review.summary, file_review.suggestions OR `--file-path`, `--summary`, `--suggestions`, `--pull-request-id` |
+| `agdt-request-changes-with-suggestion` | Request changes with structured code suggestions | pull_request_id, file_review.file_path, file_review.summary, file_review.suggestions (each suggestion must include `replacement_code`) OR `--file-path`, `--summary`, `--suggestions`, `--pull-request-id` |
 | `agdt-mark-file-reviewed` | Mark a file as reviewed (standalone) | pull_request_id, file_review.file_path |
 | `agdt-submit-file-review` | Submit batched file review | pull_request_id |
 
@@ -385,14 +385,12 @@ File review commands accept optional CLI arguments that override state values:
 
 ```bash
 # Option A: With CLI parameters (explicit, self-documenting)
-agdt-approve-file --file-path "src/app/component.ts" --content "LGTM - clean implementation"
-agdt-request-changes --file-path "src/app/service.ts" --content "Missing null check" --line 42
-agdt-request-changes-with-suggestion --file-path "src/utils.ts" --content "```suggestion
-const value = x ?? defaultValue;
-```" --line 15
+agdt-approve-file --file-path "src/app/component.ts" --summary "LGTM - clean implementation"
+agdt-request-changes --file-path "src/app/service.ts" --summary "Missing null check" --suggestions '[{"line": 42, "severity": "high", "content": "Missing null check"}]'
+agdt-request-changes-with-suggestion --file-path "src/utils.ts" --summary "Null handling needs improvement." --suggestions '[{"line": 15, "severity": "high", "content": "Use null-coalescing operator", "replacement_code": "const value = x ?? defaultValue;"}]'
 
 # Option B: Parameterless (uses current state)
-# Check current values: agdt-get file_review.file_path, agdt-get content, agdt-get line
+# Check current values: agdt-get file_review.file_path, agdt-get file_review.summary, agdt-get file_review.suggestions
 agdt-approve-file
 agdt-request-changes
 ```
@@ -403,8 +401,8 @@ All file review commands automatically:
 
 1. Post the review comment (runs as background task)
 2. Mark the file as reviewed in Azure DevOps (visible as "viewed" eye icon in PR UI)
-3. Update the review queue (`queue.json`)
-4. Print next steps (continue with next file or generate summary)
+3. Update the hierarchical review threads in Azure DevOps via PATCH requests (file, folder, and overall summary threads), then save the refreshed state to `review-state.json`
+4. Print next steps (continue with next file or advance to summary step)
 
 ### Git Workflow Actions (Background Tasks)
 
@@ -1505,6 +1503,7 @@ If `gh copilot` is not installed, a warning is printed and the prompt file path
 
 | File | Purpose |
 |------|---------|
+| `review-state.json` | Hierarchical review state: PR, folder, and file thread IDs, statuses, and suggestions |
 | `queue.json` | Review queue manifest (pending/completed files) |
 | `pull-request-files.json` | Snapshot of all PR files |
 | `pull-request-threads.json` | Snapshot of existing comment threads |
@@ -1519,22 +1518,118 @@ After a review session is active, use these commands for each file:
 # Approve a file (no issues found)
 agdt-set pull_request_id 23523
 agdt-set file_review.file_path "/path/to/file.ts"
-agdt-set content "LGTM - code follows conventions"
+agdt-set file_review.summary "LGTM - code follows conventions"
 agdt-approve-file
 
-# Request changes (with line number)
-agdt-set line 42
-agdt-set content "Consider using a more descriptive variable name"
+# Request changes (with suggestions)
+agdt-set file_review.summary "Error handling issues found."
+agdt-set file_review.suggestions '[{"line": 42, "severity": "high", "content": "Consider using a more descriptive variable name"}]'
 agdt-request-changes
 
 # Request changes with code suggestion
-agdt-set line 42
-agdt-set content "```suggestion
-const descriptiveVariableName = value;
-```"
+agdt-set file_review.summary "Naming issue found."
+agdt-set file_review.suggestions '[{"line": 42, "severity": "medium", "content": "Use a more descriptive variable name", "replacement_code": "const descriptiveVariableName = value;"}]'
 agdt-request-changes-with-suggestion
 ```
 
+#### Hierarchical Review Thread Architecture
+
+`agdt-review-pull-request` scaffolds a three-level comment hierarchy in Azure DevOps **before**
+reviewing any files:
+
+1. **File threads** — one anchored comment per file (no line context); updated via PATCH
+   as each file is approved or has changes requested
+2. **Folder threads** — one PR-level thread per top-level folder grouping, with links to
+   each file thread; status cascades from file statuses
+3. **Overall PR summary thread** — a single top-level thread linking all folder threads;
+   status cascades from folder statuses
+
+All threads are created during scaffolding and updated in-place (PATCH) as files are
+reviewed.  No separate `agdt-generate-pr-summary` call is required.
+
+#### Review State File (`review-state.json`)
+
+Location: `scripts/temp/pull-request-review/prompts/{pr_id}/review-state.json`
+
+This file tracks all thread IDs, statuses, and suggestions for the entire review session:
+
+```json
+{
+  "prId": 12345,
+  "repoId": "<guid>",
+  "repoName": "my-repo",
+  "project": "MyProject",
+  "organization": "myorg",
+  "latestIterationId": 1,
+  "scaffoldedUtc": "2024-12-19T15:50:26+00:00",
+  "overallSummary": { "threadId": 1, "commentId": 1, "status": "in-progress" },
+  "folders": {
+    "src/app": { "threadId": 2, "commentId": 1, "status": "in-progress", "files": ["/src/app/component.ts"] }
+  },
+  "files": {
+    "/src/app/component.ts": {
+      "threadId": 3,
+      "commentId": 1,
+      "folder": "src/app",
+      "fileName": "component.ts",
+      "status": "approved",
+      "summary": "Clean implementation, no issues found.",
+      "suggestions": [],
+      "previousSuggestions": null
+    }
+  }
+}
+```
+
+#### Review Status State Machine
+
+Each file, folder, and the overall PR follow this status progression:
+
+```text
+unreviewed → in-progress → approved
+                        ↘ needs-work
+```
+
+- `unreviewed` — not yet started (initial state)
+- `in-progress` — review started but not all files in scope are complete
+- `approved` — all files approved (no blocking issues)
+- `needs-work` — at least one file has changes requested
+
+#### Status Derivation Rules
+
+| Level | Rule |
+|-------|------|
+| **File** | Set directly by `agdt-approve-file` (→ `approved`) or `agdt-request-changes` (→ `needs-work`) |
+| **Folder** | All files unreviewed → `unreviewed`; ≥1 started, not all done → `in-progress`; all done, all approved → `approved`; all done, any needs-work → `needs-work` |
+| **Overall PR** | Same rules as folder, applied to folder statuses |
+
+#### Suggestion Severity Levels
+
+| Severity | Meaning |
+|----------|---------|
+| `high` | Blocking — must be addressed before the PR can be approved |
+| `medium` | Should be addressed but not strictly blocking |
+| `low` | Nice-to-have improvement; can be deferred |
+
+#### Out-of-Scope Suggestions
+
+When a suggestion does not map to a specific line in the diff (e.g., an architectural
+concern or a comment on a non-changed line), set `"out_of_scope": true` in the suggestion
+entry. The `out_of_scope` flag is persisted on the suggestion entry for classification, but
+suggestions are still posted as line-anchored file threads (not PR-level comments).
+
+#### Re-Review Flow
+
+When an author addresses feedback and requests a re-review:
+
+1. File status is reset from the terminal state (`approved`/`needs-work`) to `in-progress`
+2. Existing `suggestions` are rotated to `previousSuggestions` as an audit trail
+3. New suggestions can be added from scratch for the fresh review
+
+The rotation fires **once** per re-review cycle (when `previousSuggestions is None`).
+Once rotated — even if the original suggestions list was empty — `previousSuggestions`
+is set to `[]` (not `null`), so retries are safe and will not re-trigger rotation.
+
 #### Pipeline Usage
 
 For use in Azure DevOps pipelines (headless, no interactive terminal):
@@ -1709,6 +1804,7 @@ agdt-add-jira-comment  # Previews without posting
 | `scripts/temp/temp-get-issue-details-response.json` | `agdt-get-jira-issue` | Full Jira API response |
 | `scripts/temp/temp-get-pull-request-details-response.json` | `agdt-get-pull-request-details` | Full PR details payload |
 | `scripts/temp/pull-request-review/prompts/<pr_id>/` | `agdt-review-pull-request` | Review prompts directory |
+| `scripts/temp/pull-request-review/prompts/<pr_id>/review-state.json` | `agdt-review-pull-request` | Hierarchical review state (thread IDs, statuses, suggestions) |
 | `scripts/temp/temp-<workflow>-<step>-prompt.md` | Workflow initiation commands | Rendered workflow prompts |
 
 ### Background Task Storage Structure

{agentic_devtools-0.2.18 → agentic_devtools-0.2.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-devtools
-Version: 0.2.18
+Version: 0.2.20
 Summary: AI assistant helper commands for the Dragonfly platform
 Author: Dragonfly Team
 License-Expression: MIT

{agentic_devtools-0.2.18 → agentic_devtools-0.2.20}/agentic_devtools/__init__.py

@@ -5,4 +5,4 @@ This package provides simple CLI commands that can be easily auto-approved
 by VS Code AI assistants.
 """
 
-from agentic_devtools._version import __version__
+from agentic_devtools._version import __version__ as __version__

{agentic_devtools-0.2.18 → agentic_devtools-0.2.20}/agentic_devtools/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.18'
-__version_tuple__ = version_tuple = (0, 2, 18)
+__version__ = version = '0.2.20'
+__version_tuple__ = version_tuple = (0, 2, 20)
 
 __commit_id__ = commit_id = None

{agentic_devtools-0.2.18 → agentic_devtools-0.2.20}/agentic_devtools/cli/azure_context/management.py

@@ -78,7 +78,6 @@ def check_login_status(context: AzureContext) -> Tuple[bool, Optional[str], Opti
         - account_name: The logged-in account name (or None)
         - error_message: Error message if not logged in (or None)
     """
-    config = get_context_config(context)
     env = get_context_env(context)
 
     # Merge with current environment

{agentic_devtools-0.2.18 → agentic_devtools-0.2.20}/agentic_devtools/cli/azure_devops/__init__.py

@@ -137,6 +137,7 @@ from .review_state import (
     ReviewStatus,
     SuggestionEntry,
     add_suggestion_to_file,
+    clear_suggestions_for_re_review,
     get_file_entry,
     get_folder_entry,
     get_review_state_file_path,
@@ -273,6 +274,7 @@ __all__ = [
     "get_folder_entry",
     "update_file_status",
     "add_suggestion_to_file",
+    "clear_suggestions_for_re_review",
     # Status cascade
     "PatchOperation",
     "derive_folder_status",