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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.26.14
+Version: 0.26.15
 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.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.26.14"
+version = "0.26.15"
 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"

{specfact_cli-0.26.14 → specfact_cli-0.26.15}/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.15}/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.15"

{specfact_cli-0.26.14 → specfact_cli-0.26.15}/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.15"
 
 __all__ = ["__version__"]

{specfact_cli-0.26.14 → specfact_cli-0.26.15}/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)

{specfact_cli-0.26.14 → specfact_cli-0.26.15}/src/specfact_cli/commands/backlog_commands.py

@@ -296,6 +296,44 @@ def _parse_refined_export_markdown(content: str) -> dict[str, dict[str, Any]]:
     return result
 
 
+@beartype
+def _item_needs_refinement(
+    item: BacklogItem,
+    detector: TemplateDetector,
+    registry: TemplateRegistry,
+    template_id: str | None,
+    normalized_adapter: str | None,
+    normalized_framework: str | None,
+    normalized_persona: str | None,
+) -> bool:
+    """
+    Return True if the item needs refinement (should be processed); False if already refined (skip).
+
+    Mirrors the "already refined" skip logic used in the refine loop: checkboxes + all required
+    sections, or high confidence with no missing fields.
+    """
+    detection_result = detector.detect_template(
+        item,
+        provider=normalized_adapter,
+        framework=normalized_framework,
+        persona=normalized_persona,
+    )
+    if detection_result.template_id:
+        target = registry.get_template(detection_result.template_id) if detection_result.template_id else None
+        if target and target.required_sections:
+            has_checkboxes = bool(
+                re.search(r"^[\s]*- \[[ x]\]", item.body_markdown or "", re.MULTILINE | re.IGNORECASE)
+            )
+            all_present = all(
+                bool(re.search(rf"^#+\s+{re.escape(s)}\s*$", item.body_markdown or "", re.MULTILINE | re.IGNORECASE))
+                for s in target.required_sections
+            )
+            if has_checkboxes and all_present and not detection_result.missing_fields:
+                return False
+    already_refined = template_id is None and detection_result.confidence >= 0.8 and not detection_result.missing_fields
+    return not already_refined
+
+
 def _fetch_backlog_items(
     adapter_name: str,
     search_query: str | None = None,
@@ -424,6 +462,16 @@ def refine(
         "--limit",
         help="Maximum number of items to process in this refinement session. Use to cap batch size and avoid processing too many items at once.",
     ),
+    ignore_refined: bool = typer.Option(
+        True,
+        "--ignore-refined/--no-ignore-refined",
+        help="When set (default), exclude already-refined items from the batch so --limit applies to items that need refinement. Use --no-ignore-refined to process the first N items in order (already-refined skipped in loop).",
+    ),
+    issue_id: str | None = typer.Option(
+        None,
+        "--id",
+        help="Refine only this backlog item (issue or work item ID). Other items are ignored.",
+    ),
     template_id: str | None = typer.Option(None, "--template", "-t", help="Target template ID (default: auto-detect)"),
     auto_accept_high_confidence: bool = typer.Option(
         False, "--auto-accept-high-confidence", help="Auto-accept refinements with confidence >= 0.85"
@@ -651,6 +699,10 @@ def refine(
                 init_progress.update(validate_task, description="[green]✓[/green] Configuration validated")
 
         # Fetch backlog items with filters
+        # When ignore_refined and limit are set, fetch more candidates so we have enough after filtering
+        fetch_limit: int | None = limit
+        if ignore_refined and limit is not None and limit > 0:
+            fetch_limit = limit * 5
         with Progress(
             SpinnerColumn(),
             TextColumn("[progress.description]{task.description}"),
@@ -668,7 +720,7 @@ def refine(
                 iteration=iteration,
                 sprint=sprint,
                 release=release,
-                limit=limit,
+                limit=fetch_limit,
                 repo_owner=repo_owner,
                 repo_name=repo_name,
                 github_token=github_token,
@@ -706,6 +758,34 @@ def refine(
                 console.print("[yellow]No backlog items found.[/yellow]")
             return
 
+        # Filter by issue ID when --id is set
+        if issue_id is not None:
+            items = [i for i in items if str(i.id) == str(issue_id)]
+            if not items:
+                console.print(
+                    f"[bold red]✗[/bold red] No backlog item with id {issue_id!r} found. "
+                    "Check filters and adapter configuration."
+                )
+                raise typer.Exit(1)
+
+        # When ignore_refined (default), keep only items that need refinement; then apply limit
+        if ignore_refined:
+            items = [
+                i
+                for i in items
+                if _item_needs_refinement(
+                    i, detector, registry, template_id, normalized_adapter, normalized_framework, normalized_persona
+                )
+            ]
+            if limit is not None and len(items) > limit:
+                items = items[:limit]
+            if ignore_refined and (limit is not None or issue_id is not None):
+                console.print(
+                    f"[dim]Filtered to {len(items)} item(s) needing refinement"
+                    + (f" (limit {limit})" if limit is not None else "")
+                    + "[/dim]"
+                )
+
         # Validate export/import flags
         if export_to_tmp and import_from_tmp:
             console.print("[bold red]✗[/bold red] --export-to-tmp and --import-from-tmp are mutually exclusive")
@@ -843,8 +923,8 @@ def refine(
             console.print(f"[green]✓ Updated {len(updated_items)} backlog item(s)[/green]")
             return
 
-        # Apply limit if specified
-        if limit and len(items) > limit:
+        # Apply limit if specified (when not ignore_refined; when ignore_refined we already filtered and sliced)
+        if not ignore_refined and limit is not None and len(items) > limit:
             items = items[:limit]
             console.print(f"[yellow]Limited to {limit} items (found {len(items)} total)[/yellow]")
         else: