specfact-cli 0.26.14__tar.gz → 0.26.16__tar.gz

{specfact_cli-0.26.14 → specfact_cli-0.26.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.26.14
+Version: 0.26.16
 Summary: Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git

{specfact_cli-0.26.14 → specfact_cli-0.26.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.26.14"
+version = "0.26.16"
 description = "Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -272,9 +272,9 @@ TOKENIZERS_PARALLELISM = "false" # Good practice if using HuggingFace tokenizers
 
 [tool.hatch.envs.hatch-test.scripts]
 # Adapted from template, adjust JUnit path if necessary
-run = "pytest --timeout=5 --junitxml=logs/tests/junit/test-results.xml {args}" # Removed --auto-capture-workflow if not used
-run-cov = "coverage run -m pytest --timeout=5 --junitxml=logs/tests/junit/test-results.xml {args}"
-cov = "coverage run -m pytest --timeout=5 --junitxml=logs/tests/junit/test-results.xml {args}"
+run = "pytest --timeout=30 --junitxml=logs/tests/junit/test-results.xml {args}" # 30s for code analysis/semgrep/graph tests under xdist
+run-cov = "coverage run -m pytest --timeout=30 --junitxml=logs/tests/junit/test-results.xml {args}"
+cov = "coverage run -m pytest --timeout=30 --junitxml=logs/tests/junit/test-results.xml {args}"
 cov-combine = "coverage combine --quiet"
 xml = "coverage xml -o logs/tests/coverage/coverage.xml"
 run-html = "coverage html --data-file=logs/tests/coverage/.coverage -d logs/tests/coverage/html"
@@ -334,6 +334,10 @@ output = "logs/tests/coverage/coverage.xml"
 mode = "strict"
 default_fixture_loop_scope = "function"
 
+[tool.pytest-timeout]
+timeout = 30
+method = "thread"
+
 [tool.hatch.build]
 dev-mode-dirs = ["src","tools"]
 

specfact_cli-0.26.16/resources/prompts/specfact.backlog-daily.md

@@ -0,0 +1,109 @@
+---
+description: "Daily standup and sprint review with story-by-story walkthrough"
+---
+
+# SpecFact Daily Standup Command
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Run a daily standup view and optional interactive walkthrough of backlog items (GitHub Issues, Azure DevOps work items) with the DevOps team: list items in scope, review story-by-story, highlight current focus, surface issues or open questions, and allow adding discussion notes as annotation comments on the issue.
+
+**When to use:** Daily standup, sprint review, quick status sync with the team.
+
+**Quick:** `/specfact.daily` or `/specfact.backlog-daily` with optional adapter and filters. From a clone, org/repo or org/project are auto-detected from git remote.
+
+## Parameters
+
+### Required
+
+- `ADAPTER` - Backlog adapter name (github, ado, etc.)
+
+### Adapter Configuration (same as backlog-refine)
+
+**GitHub:** `--repo-owner`, `--repo-name`, `--github-token` (optional).  
+**Azure DevOps:** `--ado-org`, `--ado-project`, `--ado-team` (optional), `--ado-base-url`, `--ado-token` (optional).
+
+When run from a **clone**, org/repo or org/project are inferred from `git remote get-url origin`; no need to pass them unless overriding.
+
+### Filters
+
+- `--state STATE` - Filter by state (e.g. open, Active)
+- `--assignee USERNAME` or `--assignee me` - Filter by assignee
+- `--sprint SPRINT` / `--iteration PATH` - Filter by sprint/iteration (e.g. `current`)
+- `--limit N` - Max items (default 20)
+- `--blockers-first` - Sort items with blockers first
+- `--show-unassigned` / `--unassigned-only` - Include or show only unassigned items
+
+### Daily-Specific Options
+
+- `--interactive` - Step-by-step review: select items with arrow keys, view full detail (refine-like) and **existing comments** on each issue
+- `--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**
+- `--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)
+
+## Workflow
+
+### Step 1: Run Daily Standup
+
+Execute the CLI with adapter and optional filters:
+
+```bash
+specfact backlog daily $ADAPTER [--state open] [--sprint current] [--assignee me] [--limit 20]
+```
+
+Or use the slash command with arguments: `/specfact.backlog-daily --adapter ado --sprint current`
+
+**What you see:** A standup table (assigned items) and a "Pending / open for commitment" table (unassigned items in scope). Each row shows ID, title, status, last updated, and optional yesterday/today/blockers from the item body.
+
+### Step 2: Interactive Story-by-Story Review (with DevOps team)
+
+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).
+   - **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").
+   - **Move to next** only when the team is done with this story (e.g. "next", "done").
+
+2. **Rules**:
+   - Do not update the backlog item body or title unless the user asks for a refinement (use `specfact backlog refine` for that).
+   - Comments are for **discussion notes** and standup updates; keep them short and actionable.
+   - If the adapter does not support comments, report that clearly and skip adding comments.
+
+3. **Navigation**: After each story, offer "Next story", "Previous story", "Back to list", "Exit" (or equivalent) so the team can move through the list without re-running the command.
+
+### Step 3: Generate Standup Summary (optional)
+
+When the user has run `specfact backlog daily ... --summarize` or `--summarize-to PATH`, the output is a **prompt** containing:
+
+- A short instruction: generate a concise daily standup summary from the following data.
+- Filter context (adapter, state, sprint, assignee, limit).
+- Per-item data (same as `--copilot-export`: ID, title, status, assignees, last updated, progress, blockers).
+
+**Use this output** by pasting it into Copilot or invoking the slash command `specfact.daily` with this context, so the AI can produce a short narrative summary (e.g. "Today's standup: 3 in progress, 1 blocked, 2 pending commitment …").
+
+## 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.
+
+## CLI Enforcement
+
+- Execute `specfact backlog daily` (or equivalent) first; use its output as context.
+- Use `--interactive` for story-by-story walkthrough; use `--summarize` or `--summarize-to` when a standup summary prompt is needed.
+- Use `--copilot-export` when you need a file of item summaries for reference during standup.
+
+## Context
+
+{ARGS}

{specfact_cli-0.26.14 → specfact_cli-0.26.16}/resources/prompts/specfact.backlog-refine.md

@@ -69,6 +69,8 @@ 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)
+- `--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)
 - `--framework FRAMEWORK` - Filter templates by framework (agile, scrum, safe, kanban)
 
@@ -162,6 +164,30 @@ specfact backlog refine $ADAPTER \
    - Use `:quit` or `:abort` to cancel the entire session gracefully
    - Session cancellation shows summary and exits without error
 
+### Interactive refinement (Copilot mode)
+
+When refining backlog items in Copilot mode (e.g. after export to tmp or during a refinement session), follow this **per-story loop** so the PO and stakeholders can review and approve before any update:
+
+1. **For each story** (one at a time):
+   - **Present** the refined story in a clear, readable format:
+     - Use headings for Title, Body, Acceptance Criteria, Metrics.
+     - Use tables or panels for structured data so it is easy to scan.
+   - **Assess specification level** so the DevOps team knows if the story is ready, under-specified, or over-specified:
+     - **Under-specified**: Missing acceptance criteria, vague scope, unclear "so that" or user value. List evidence (e.g. "No AC", "Scope could mean X or Y"). Suggest what to add.
+     - **Over-specified**: Too much implementation detail, too many sub-steps for one story, or solution prescribed instead of outcome. List evidence and suggest what to trim or split.
+     - **Fit for scope and intent**: Clear persona, capability, benefit, and testable AC; appropriate size. State briefly why it is ready (and, if DoR is in use, that DoR is satisfied).
+   - **List ambiguities** or open questions (e.g. unclear scope, missing acceptance criteria, conflicting assumptions).
+   - **Ask** the PO and other stakeholders for clarification: "Please review the refined story above. Do you want any changes? Any ambiguities to resolve? Should this story be split?"
+   - **If the user provides feedback**: Re-refine the story incorporating the feedback, then repeat from "Present" for this story.
+   - **Only when the user explicitly approves** (e.g. "looks good", "approved", "no changes"): Mark this story as done and move to the **next** story.
+   - **Do not update** the backlog item (or write to the refined file as final) until the user has approved this story.
+
+2. **Formatting**:
+   - Use clear headings, bullet lists, and optional tables/panels so refinement sessions are easy to follow and enjoyable.
+   - Keep each story’s block self-contained so stakeholders can focus on one item at a time.
+
+3. **Rule**: The backlog item (or exported block) must only be updated/finalized **after** the user has approved the refined content for that story. Then proceed to the next story with the same process.
+
 ### Step 3: Present Results
 
 Display refinement results:

{specfact_cli-0.26.14 → specfact_cli-0.26.16}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.26.14"
+__version__ = "0.26.16"

{specfact_cli-0.26.14 → specfact_cli-0.26.16}/src/specfact_cli/__init__.py

@@ -9,6 +9,6 @@ This package provides command-line tools for:
 - Validating reproducibility
 """
 
-__version__ = "0.26.14"
+__version__ = "0.26.16"
 
 __all__ = ["__version__"]

{specfact_cli-0.26.14 → specfact_cli-0.26.16}/src/specfact_cli/adapters/ado.py

@@ -3107,6 +3107,11 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         return filtered_items
 
+    @beartype
+    def supports_add_comment(self) -> bool:
+        """Whether this adapter can add comments (requires token, org, project)."""
+        return bool(self.api_token and self.org and self.project)
+
     @beartype
     def add_comment(self, item: BacklogItem, comment: str) -> bool:
         """

{specfact_cli-0.26.14 → specfact_cli-0.26.16}/src/specfact_cli/adapters/github.py

@@ -2644,6 +2644,11 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         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)."""
+        return bool(self.api_token and self.repo_owner and self.repo_name)
+
     @beartype
     def add_comment(self, item: BacklogItem, comment: str) -> bool:
         """
@@ -2681,6 +2686,31 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         except Exception:
             return False
 
+    @beartype
+    def get_comments(self, item: BacklogItem) -> list[str]:
+        """
+        Fetch comments for a GitHub issue.
+
+        Args:
+            item: BacklogItem to fetch comments for
+
+        Returns:
+            List of comment body strings, or empty list on error
+        """
+        if not self.repo_owner or not self.repo_name:
+            return []
+        issue_number: int | None = None
+        if item.id.isdigit():
+            issue_number = int(item.id)
+        elif item.url:
+            match = re.search(r"/issues/(\d+)", item.url)
+            if match:
+                issue_number = int(match.group(1))
+        if not issue_number:
+            return []
+        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)]
+
     def update_backlog_item(self, item: BacklogItem, update_fields: list[str] | None = None) -> BacklogItem:
         """
         Update a GitHub issue.

{specfact_cli-0.26.14 → specfact_cli-0.26.16}/src/specfact_cli/backlog/adapters/base.py

@@ -147,6 +147,20 @@ class BacklogAdapter(ABC):
         """
         return None
 
+    @beartype
+    @ensure(lambda result: isinstance(result, bool), "Must return boolean")
+    def supports_add_comment(self) -> bool:
+        """
+        Whether this adapter supports adding comments to backlog items.
+
+        Returns:
+            True if add_comment will attempt to post, False otherwise
+
+        Note:
+            Default is False. Override in adapters that support issue comments.
+        """
+        return False
+
     @beartype
     def add_comment(self, item: BacklogItem, comment: str) -> bool:
         """
@@ -164,3 +178,20 @@ class BacklogAdapter(ABC):
             can use the default False implementation.
         """
         return False
+
+    @beartype
+    def get_comments(self, item: BacklogItem) -> list[str]:
+        """
+        Fetch comments for a backlog item (optional).
+
+        Args:
+            item: BacklogItem to fetch comments for
+
+        Returns:
+            List of comment body strings, or empty list if not supported or on error
+
+        Note:
+            This is an optional method. Adapters that don't support fetching comments
+            can use the default empty list implementation.
+        """
+        return []

{specfact_cli-0.26.14 → specfact_cli-0.26.16}/src/specfact_cli/cli.py

@@ -454,6 +454,7 @@ def cli_main() -> None:
         console.print()  # Empty line after banner
     elif not is_help_or_version and not is_test_mode:
         # Show simple version line like other CLIs (skip for help/version commands and in test mode)
+        # Printed before startup checks so users see output immediately (important with slow checks e.g. xagt)
         print_version_line()
 
     # Run startup checks (template validation and version check)