specfact-cli 0.30.1__tar.gz → 0.30.2__tar.gz

{specfact_cli-0.30.1 → specfact_cli-0.30.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.30.1
+Version: 0.30.2
 Summary: The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git

{specfact_cli-0.30.1 → specfact_cli-0.30.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.30.1"
+version = "0.30.2"
 description = "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases."
 readme = "README.md"
 requires-python = ">=3.11"

{specfact_cli-0.30.1 → specfact_cli-0.30.2}/resources/prompts/specfact.backlog-daily.md

@@ -37,8 +37,12 @@ When run from a **clone**, org/repo or org/project are inferred from `git remote
 
 - `--state STATE` - Filter by state (e.g. open, Active)
 - `--assignee USERNAME` or `--assignee me` - Filter by assignee
+- `--search QUERY` - Provider-specific search query
+- `--release RELEASE` - Filter by release identifier
+- `--id ISSUE_ID` - Filter to one exact backlog item ID
 - `--sprint SPRINT` / `--iteration PATH` - Filter by sprint/iteration (e.g. `current`)
 - `--limit N` - Max items (default 20)
+- `--first-issues N` / `--last-issues N` - Optional issue window (oldest/newest by numeric ID, mutually exclusive)
 - `--blockers-first` - Sort items with blockers first
 - `--show-unassigned` / `--unassigned-only` - Include or show only unassigned items
 
@@ -48,8 +52,11 @@ When run from a **clone**, org/repo or org/project are inferred from `git remote
 - `--copilot-export PATH` - Write summarized progress per story to a file for Copilot slash-command use
 - `--summarize` - Output a prompt (instruction + filter context + standup data) to **stdout** for Copilot or slash command to generate a standup summary
 - `--summarize-to PATH` - Write the same summarize prompt to a **file**
+- `--comments` / `--annotations` - Include descriptions and comments in `--copilot-export` and summarize output
+- `--first-comments N` / `--last-comments N` - Optional comment window for export/summarize outputs (`--comments`); default includes all comments
 - `--suggest-next` - In interactive mode, show suggested next item by value score
 - `--post` with `--yesterday`, `--today`, `--blockers` - Post a standup comment to the first item's issue (when adapter supports comments)
+- Interactive navigation action `Post standup update` - Post yesterday/today/blockers to the currently selected story during `--interactive` walkthrough
 
 ## Workflow
 
@@ -70,10 +77,12 @@ Or use the slash command with arguments: `/specfact.backlog-daily --adapter ado
 When the user runs **`--interactive`** (or the slash command drives an interactive flow):
 
 1. **For each story** (one at a time):
-   - **Present** the item: ID, title, status, assignees, last updated, description, acceptance criteria, standup fields (yesterday/today/blockers), and **existing comments** annotated to that issue (when the adapter supports fetching comments).
+   - **Present** the item: ID, title, status, assignees, last updated, description, acceptance criteria, standup fields (yesterday/today/blockers), and the **latest existing comment** (when the adapter supports fetching comments).
+   - **Interactive comment scope**: If older comments exist, explicitly mention the count of hidden comments and guide users to export options for full context.
    - **Highlight current focus**: What is the team member working on? What is the next intended step?
    - **Surface issues or open questions**: Blockers, ambiguities, dependencies, or decisions needed.
    - **Allow discussion notes**: If the team agrees, suggest or add a **comment** on the issue (e.g. "Standup YYYY-MM-DD: …" or "Discussion: …") so the discussion is captured as an annotation. Only add comments when the user explicitly approves (e.g. "add that as a comment").
+   - If in CLI interactive navigation, use **Post standup update** to write the note to the selected story directly.
    - **Move to next** only when the team is done with this story (e.g. "next", "done").
 
 2. **Rules**:
@@ -95,8 +104,9 @@ When the user has run `specfact backlog daily ... --summarize` or `--summarize-t
 
 ## Comments on Issues
 
-- **Interactive detail view** shows **existing comments** on each issue (GitHub issue comments, ADO work item discussion) when the adapter supports it. Use them to understand prior discussion and avoid repeating questions.
-- **Adding comments**: When the team agrees to record a discussion note or standup update, add it as a comment on the issue (via `--post` for standup lines, or by guiding the user to run the CLI/post manually). Do not invent comments; only suggest or add when the user approves.
+- **Interactive detail view** shows only the **latest comment** plus a hint when additional comments exist, to keep standup readable.
+- **Full comment context**: use `--copilot-export <path> --comments` or `--summarize --comments` (optional `--first-comments N` / `--last-comments N`) to include full or scoped comment history.
+- **Adding comments**: When the team agrees to record a discussion note or standup update, add it as a comment on the issue (via `--post` for first-item standup lines or interactive **Post standup update** for selected stories). Do not invent comments; only suggest or add when the user approves.
 
 ## CLI Enforcement
 

{specfact_cli-0.30.1 → specfact_cli-0.30.2}/resources/prompts/specfact.backlog-refine.md

@@ -69,6 +69,7 @@ Refine backlog items from DevOps tools (GitHub Issues, Azure DevOps, etc.) into
   - Ambiguous name-only matches will prompt for explicit iteration path
 - `--release RELEASE` - Filter by release identifier (case-insensitive)
 - `--limit N` - Maximum number of items to process in this refinement session (caps batch size)
+- `--first-issues N` / `--last-issues N` - Process only the first or last N items after filters/refinement checks (mutually exclusive; sorted by numeric issue/work-item ID, lower=older, higher=newer)
 - `--ignore-refined` / `--no-ignore-refined` - When set (default), exclude already-refined items so `--limit` applies to items that need refinement. Use `--no-ignore-refined` to process the first N items in order.
 - `--id ISSUE_ID` - Refine only this backlog item (issue or work item ID). Other items are ignored.
 - `--persona PERSONA` - Filter templates by persona (product-owner, architect, developer)
@@ -91,13 +92,23 @@ Refine backlog items from DevOps tools (GitHub Issues, Azure DevOps, etc.) into
 - `--export-to-tmp` - Export backlog items to temporary file for copilot processing (default: `/tmp/specfact-backlog-refine-<timestamp>.md`)
 - `--import-from-tmp` - Import refined content from temporary file after copilot processing (default: `/tmp/specfact-backlog-refine-<timestamp>-refined.md`)
 - `--tmp-file PATH` - Custom temporary file path (overrides default)
+- `--first-comments N` / `--last-comments N` - Optional comment window for preview and write-mode prompt context (default preview shows last 2; write prompts include full comments by default)
 
 **Export/Import Workflow**:
 
 1. Export items: `specfact backlog refine --adapter github --export-to-tmp --repo-owner OWNER --repo-name NAME`
-2. Process with copilot: Open exported file, use copilot to refine items, save as `-refined.md`
+2. Process with copilot: Open exported file and follow the embedded `## Copilot Instructions` and per-item template guidance (`Target Template`, `Required Sections`, `Optional Sections`). Save as `-refined.md`
 3. Import refined: `specfact backlog refine --adapter github --import-from-tmp --repo-owner OWNER --repo-name NAME --write`
 
+When refining from an exported file, treat the embedded instructions in that file as the source of truth for required structure and formatting.
+
+**Comment context in export**:
+
+- Export includes item comments when adapter supports comment retrieval (GitHub + ADO).
+- Export always includes full comment history (no truncation).
+- Use `--first-comments N` or `--last-comments N` only to adjust preview output density.
+- For refined import readiness, the `-refined.md` artifact should omit the instruction header and keep only item sections.
+
 ### Definition of Ready (DoR)
 
 - `--check-dor` - Check Definition of Ready (DoR) rules before refinement (loads from `.specfact/dor.yaml`)

{specfact_cli-0.30.1 → specfact_cli-0.30.2}/src/specfact_cli/__init__.py

@@ -8,6 +8,6 @@ This package provides command-line tools for:
 - Supporting agile ceremonies and team workflows
 """
 
-__version__ = "0.30.1"
+__version__ = "0.30.2"
 
 __all__ = ["__version__"]

{specfact_cli-0.30.1 → specfact_cli-0.30.2}/src/specfact_cli/adapters/ado.py

@@ -2356,18 +2356,39 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         if not self.api_token:
             return []
 
-        url = f"{self.base_url}/{org}/{project}/_apis/wit/workitems/{work_item_id}/comments?api-version=7.1"
+        url = f"{self.base_url}/{org}/{project}/_apis/wit/workItems/{work_item_id}/comments"
         headers = {
             "Accept": "application/json",
             **self._auth_headers(),
         }
 
         try:
-            response = requests.get(url, headers=headers, timeout=30)
-            response.raise_for_status()
-            # ADO API returns comments in a 'comments' array within the response
-            response_data = response.json()
-            return response_data.get("comments", [])
+            comments: list[dict[str, Any]] = []
+            continuation_token: str | None = None
+            seen_tokens: set[str] = set()
+
+            while True:
+                params: dict[str, Any] = {"api-version": "7.1-preview.4", "$top": 200, "order": "asc"}
+                if continuation_token:
+                    params["continuationToken"] = continuation_token
+
+                response = requests.get(url, headers=headers, params=params, timeout=30)
+                response.raise_for_status()
+                response_data = response.json()
+
+                raw_comments = response_data.get("comments", [])
+                if isinstance(raw_comments, list):
+                    comments.extend([c for c in raw_comments if isinstance(c, dict)])
+
+                next_token = response.headers.get("x-ms-continuationtoken") or response_data.get("continuationToken")
+                if not next_token or not isinstance(next_token, str):
+                    break
+                if next_token in seen_tokens:
+                    break
+                seen_tokens.add(next_token)
+                continuation_token = next_token
+
+            return comments
         except requests.RequestException:
             # Return empty list on error - comments are optional
             return []
@@ -3145,6 +3166,35 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         except Exception:
             return False
 
+    @beartype
+    def get_comments(self, item: BacklogItem) -> list[str]:
+        """
+        Fetch comments for an Azure DevOps work item.
+
+        Args:
+            item: BacklogItem to fetch comments for
+
+        Returns:
+            List of comment body strings, or empty list on error
+        """
+        if not self.org or not self.project:
+            return []
+
+        if not item.id.isdigit():
+            return []
+
+        raw = self._get_work_item_comments(self.org, self.project, int(item.id))
+        comment_texts: list[str] = []
+        for comment in raw:
+            if not isinstance(comment, dict):
+                continue
+            text = comment.get("text") or comment.get("body")
+            if isinstance(text, str):
+                stripped = text.strip()
+                if stripped:
+                    comment_texts.append(stripped)
+        return comment_texts
+
     @beartype
     @require(lambda item: isinstance(item, BacklogItem), "Item must be BacklogItem")
     @require(

{specfact_cli-0.30.1 → specfact_cli-0.30.2}/src/specfact_cli/adapters/github.py

@@ -2526,7 +2526,11 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         if filters.assignee:
             # Strip leading @ if present for GitHub search
             assignee_value = filters.assignee.lstrip("@")
-            query_parts.append(f"assignee:{assignee_value}")
+            normalized_assignee_value = BacklogFilters.normalize_filter_value(assignee_value)
+            if normalized_assignee_value == "me":
+                query_parts.append("assignee:@me")
+            else:
+                query_parts.append(f"assignee:{assignee_value}")
 
         if filters.labels:
             for label in filters.labels:
@@ -2585,24 +2589,25 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             # Normalize assignee filter (strip @, lowercase)
             assignee_filter = filters.assignee.lstrip("@")
             normalized_assignee = BacklogFilters.normalize_filter_value(assignee_filter)
-
-            filtered_items = [
-                item
-                for item in filtered_items
-                if any(
-                    # Match against login (case-insensitive)
-                    BacklogFilters.normalize_filter_value(assignee) == normalized_assignee
-                    # Or match against display name if available (case-insensitive)
-                    or (
-                        hasattr(item, "provider_fields")
-                        and isinstance(item.provider_fields, dict)
-                        and item.provider_fields.get("assignee_login")
-                        and BacklogFilters.normalize_filter_value(item.provider_fields["assignee_login"])
-                        == normalized_assignee
+            # `me` is provider-relative identity and should rely on GitHub query semantics.
+            if normalized_assignee != "me":
+                filtered_items = [
+                    item
+                    for item in filtered_items
+                    if any(
+                        # Match against login (case-insensitive)
+                        BacklogFilters.normalize_filter_value(assignee) == normalized_assignee
+                        # Or match against display name if available (case-insensitive)
+                        or (
+                            hasattr(item, "provider_fields")
+                            and isinstance(item.provider_fields, dict)
+                            and item.provider_fields.get("assignee_login")
+                            and BacklogFilters.normalize_filter_value(item.provider_fields["assignee_login"])
+                            == normalized_assignee
+                        )
+                        for assignee in item.assignees
                     )
-                    for assignee in item.assignees
-                )
-            ]
+                ]
 
         if filters.iteration:
             filtered_items = [item for item in filtered_items if item.iteration and item.iteration == filters.iteration]
@@ -2633,17 +2638,6 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         return filtered_items
 
-    @beartype
-    @require(lambda item: isinstance(item, BacklogItem), "Item must be BacklogItem")
-    @require(
-        lambda item, update_fields: update_fields is None or isinstance(update_fields, list),
-        "Update fields must be None or list",
-    )
-    @ensure(lambda result: isinstance(result, BacklogItem), "Must return BacklogItem")
-    @ensure(
-        lambda result, item: result.id == item.id and result.provider == item.provider,
-        "Updated item must preserve id and provider",
-    )
     @beartype
     def supports_add_comment(self) -> bool:
         """Whether this adapter can add comments (requires token and repo)."""
@@ -2711,6 +2705,17 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         raw = self._get_issue_comments(self.repo_owner, self.repo_name, issue_number)
         return [str(c.get("body", "")).strip() for c in raw if isinstance(c, dict)]
 
+    @beartype
+    @require(lambda item: isinstance(item, BacklogItem), "Item must be BacklogItem")
+    @require(
+        lambda item, update_fields: update_fields is None or isinstance(update_fields, list),
+        "Update fields must be None or list",
+    )
+    @ensure(lambda result: isinstance(result, BacklogItem), "Must return BacklogItem")
+    @ensure(
+        lambda result, item: result.id == item.id and result.provider == item.provider,
+        "Updated item must preserve id and provider",
+    )
     def update_backlog_item(self, item: BacklogItem, update_fields: list[str] | None = None) -> BacklogItem:
         """
         Update a GitHub issue.

{specfact_cli-0.30.1 → specfact_cli-0.30.2}/src/specfact_cli/backlog/ai_refiner.py

@@ -73,8 +73,14 @@ class BacklogAIRefiner:
     @beartype
     @require(lambda self, item: isinstance(item, BacklogItem), "Item must be BacklogItem")
     @require(lambda self, template: isinstance(template, BacklogTemplate), "Template must be BacklogTemplate")
+    @require(
+        lambda self, comments=None: comments is None or isinstance(comments, list),
+        "Comments must be a list of strings or None",
+    )
     @ensure(lambda result: isinstance(result, str) and len(result) > 0, "Must return non-empty prompt string")
-    def generate_refinement_prompt(self, item: BacklogItem, template: BacklogTemplate) -> str:
+    def generate_refinement_prompt(
+        self, item: BacklogItem, template: BacklogTemplate, comments: list[str] | None = None
+    ) -> str:
         """
         Generate prompt for IDE AI copilot to refine backlog item.
 
@@ -122,6 +128,16 @@ The adapter will map these back to separate ADO fields during writeback."""
         if item.work_item_type:
             metrics_info += f"\nWork Item Type: {item.work_item_type}"
 
+        comment_lines: list[str] = []
+        if comments:
+            comment_lines.append("Comments (latest discussion context):")
+            for index, comment in enumerate(comments, 1):
+                comment_lines.append(f"{index}. {comment}")
+        else:
+            comment_lines.append("Comments (latest discussion context):")
+            comment_lines.append("- No comments found")
+        comments_info = "\n".join(comment_lines)
+
         prompt = f"""Transform the following backlog item into the {template.name} template format.
 
 Original Backlog Item:
@@ -132,6 +148,8 @@ Provider: {item.provider}
 Body:
 {item.body_markdown}
 
+{comments_info}
+
 Target Template: {template.name}
 Description: {template.description}