specfact-cli 0.11.4__tar.gz → 0.11.5__tar.gz

{specfact_cli-0.11.4 → specfact_cli-0.11.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.11.4
+Version: 0.11.5
 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.11.4 → specfact_cli-0.11.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.11.4"
+version = "0.11.5"
 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.11.5/resources/prompts/specfact.03-review.md

@@ -0,0 +1,220 @@
+---
+description: Review project bundle to identify ambiguities, resolve gaps, and prepare for promotion.
+---
+
+# SpecFact Review Command
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Review project bundle to identify/resolve ambiguities and missing information. Asks targeted questions for promotion readiness.
+
+**When to use:** After import/creation, before promotion, when clarification needed.
+
+**Quick:** `/specfact.03-review` (uses active plan) or `/specfact.03-review legacy-api`
+
+## Parameters
+
+### Target/Input
+
+- `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`)
+- `--category CATEGORY` - Focus on specific taxonomy category. Default: None (all categories)
+
+### Output/Results
+
+- `--list-questions` - Output questions in JSON format. Default: False
+- `--list-findings` - Output all findings in structured format. Default: False
+- `--findings-format FORMAT` - Output format: json, yaml, or table. Default: json for non-interactive, table for interactive
+
+### Behavior/Options
+
+- `--no-interactive` - Non-interactive mode (for CI/CD). Default: False (interactive mode)
+- `--answers JSON` - JSON object with question_id -> answer mappings. Default: None
+- `--auto-enrich` - Automatically enrich vague acceptance criteria. Default: False
+
+### Advanced/Configuration
+
+- `--max-questions INT` - Maximum questions per session. Default: 5 (range: 1-10)
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+- Extract bundle name (defaults to active plan if not specified)
+- Extract optional parameters (max-questions, category, etc.)
+
+### Step 2: Execute CLI to Get Findings
+
+**First, get findings to understand what needs enrichment:**
+
+```bash
+specfact plan review [<bundle-name>] --list-findings --findings-format json
+# Uses active plan if bundle not specified
+```
+
+This outputs all ambiguities and missing information in structured format.
+
+### Step 3: Create Enrichment Report (if needed)
+
+Based on the findings, create a Markdown enrichment report that addresses:
+
+- **Business Context**: Priorities, constraints, unknowns
+- **Confidence Adjustments**: Feature confidence score updates (if needed)
+- **Missing Features**: New features to add (if any)
+- **Manual Updates**: Guidance for updating `idea.yaml` fields like `target_users`, `value_hypothesis`, `narrative`
+
+**Enrichment Report Format:**
+
+```markdown
+## Business Context
+
+### Priorities
+- Priority 1
+- Priority 2
+
+### Constraints
+- Constraint 1
+- Constraint 2
+
+### Unknowns
+- Unknown 1
+- Unknown 2
+
+## Confidence Adjustments
+
+FEATURE-KEY → 0.95
+FEATURE-OTHER → 0.8
+
+## Missing Features
+
+(If any features are missing)
+
+## Recommendations for Manual Updates
+
+### idea.yaml Updates Required
+
+**target_users:**
+- Primary: [description]
+- Secondary: [description]
+
+**value_hypothesis:**
+[Value proposition]
+
+**narrative:**
+[Improved narrative]
+```
+
+### Step 4: Apply Enrichment
+
+#### Option A: Use enrichment to answer review questions
+
+Create answers JSON from enrichment report and use with review:
+
+```bash
+specfact plan review [<bundle-name>] --answers '{"Q001": "answer1", "Q002": "answer2"}'
+```
+
+#### Option B: Update idea fields directly via CLI
+
+Use `plan update-idea` to update idea fields from enrichment recommendations:
+
+```bash
+specfact plan update-idea --bundle [<bundle-name>] --value-hypothesis "..." --narrative "..." --target-users "..."
+```
+
+#### Option C: Apply enrichment via import (only if bundle needs regeneration)
+
+```bash
+specfact import from-code [<bundle-name>] --repo . --enrichment enrichment-report.md
+```
+
+**Note:**
+
+- **Preferred**: Use Option A (answers) or Option B (update-idea) for most cases
+- Only use Option C if you need to regenerate the bundle
+- Never manually edit `.specfact/` files directly - always use CLI commands
+
+### Step 5: Present Results
+
+- Display Q&A, sections touched, coverage summary (initial/updated)
+- Note: Clarifications don't affect hash (stable across review sessions)
+- If enrichment report was created, summarize what was addressed
+
+## CLI Enforcement
+
+**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
+
+**Rules:** Execute CLI first, use `--no-interactive` in CI/CD, never modify `.specfact/` directly, use CLI output as grounding.
+
+## Expected Output
+
+### Success
+
+```text
+✓ Review complete: 5 question(s) answered
+
+Project Bundle: legacy-api
+Questions Asked: 5
+
+Sections Touched:
+  • idea.narrative
+  • features[FEATURE-001].acceptance
+  • features[FEATURE-002].outcomes
+
+Coverage Summary:
+  ✅ Functional Scope: clear
+  ✅ Technical Constraints: clear
+  ⚠️ Business Context: partial
+```
+
+### Error (Missing Bundle)
+
+```text
+✗ Project bundle 'legacy-api' not found
+Create one with: specfact plan init legacy-api
+```
+
+## Common Patterns
+
+```bash
+# Get findings first
+/specfact.03-review --list-findings                    # List all findings
+/specfact.03-review --list-findings --findings-format json  # JSON format for enrichment
+
+# Interactive review
+/specfact.03-review                                    # Uses active plan
+/specfact.03-review legacy-api                         # Specific bundle
+/specfact.03-review --max-questions 3                  # Limit questions
+/specfact.03-review --category "Functional Scope"      # Focus category
+
+# Non-interactive with answers
+/specfact.03-review --answers '{"Q001": "answer"}'     # Provide answers directly
+/specfact.03-review --list-questions                   # Output questions as JSON
+
+# Auto-enrichment
+/specfact.03-review --auto-enrich                     # Auto-enrich vague criteria
+```
+
+## Enrichment Workflow
+
+**Typical workflow when enrichment is needed:**
+
+1. **Get findings**: `specfact plan review --list-findings --findings-format json`
+2. **Analyze findings**: Review missing information (target_users, value_hypothesis, etc.)
+3. **Create enrichment report**: Write Markdown file addressing findings
+4. **Apply enrichment**:
+   - **Preferred**: Use enrichment to create `--answers` JSON and run `plan review --answers`
+   - **Alternative**: Use `plan update-idea` to update idea fields directly
+   - **Last resort**: If bundle needs regeneration, use `import from-code --enrichment`
+5. **Verify**: Run `plan review` again to confirm improvements
+
+## Context
+
+{ARGS}

{specfact_cli-0.11.4 → specfact_cli-0.11.5}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Define the package version (kept in sync with pyproject.toml and setup.py)
-__version__ = "0.11.4"
+__version__ = "0.11.5"

{specfact_cli-0.11.4 → specfact_cli-0.11.5}/src/specfact_cli/__init__.py

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

{specfact_cli-0.11.4 → specfact_cli-0.11.5}/src/specfact_cli/commands/plan.py

@@ -3607,10 +3607,12 @@ def _handle_no_questions_case(
                 )
                 console.print(f"  {status_icon} {cat.value}: {status.value}")
 
+    return
+
 
 @beartype
 @require(lambda questions_to_ask: isinstance(questions_to_ask, list), "Questions must be list")
-@ensure(lambda result: None, "Must return None")
+@ensure(lambda result: result is None, "Must return None")
 def _handle_list_questions_mode(questions_to_ask: list[tuple[Any, str]]) -> None:
     """
     Handle --list-questions mode by outputting questions as JSON.
@@ -3638,6 +3640,8 @@ def _handle_list_questions_mode(questions_to_ask: list[tuple[Any, str]]) -> None
     sys.stdout.write("\n")
     sys.stdout.flush()
 
+    return
+
 
 @beartype
 @require(lambda answers: isinstance(answers, str), "Answers must be string")
@@ -3824,7 +3828,7 @@ def _ask_questions_interactive(
 @require(lambda report: report is not None, "Report must not be None")
 @require(lambda current_stage: isinstance(current_stage, str), "Current stage must be str")
 @require(lambda today_session: today_session is not None, "Today session must not be None")
-@ensure(lambda result: None, "Must return None")
+@ensure(lambda result: result is None, "Must return None")
 def _display_review_summary(
     plan_bundle: PlanBundle,
     scanner: Any,  # AmbiguityScanner
@@ -3898,6 +3902,8 @@ def _display_review_summary(
         console.print("  • Plan is ready for approval")
         console.print("  • Run: specfact plan promote --stage approved")
 
+    return
+
 
 @app.command("review")
 @beartype

specfact_cli-0.11.5/src/specfact_cli/utils/progress.py

@@ -0,0 +1,182 @@
+"""
+Progress display utilities for consistent UI/UX across all commands.
+
+This module provides unified progress display functions that ensure
+consistent formatting and user experience across all CLI commands.
+Includes timing information for visibility into operation duration.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from pathlib import Path
+from time import time
+from typing import Any
+
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+
+from specfact_cli.models.project import ProjectBundle
+from specfact_cli.utils.bundle_loader import load_project_bundle, save_project_bundle
+
+
+console = Console()
+
+
+def _is_test_mode() -> bool:
+    """Check if running in test mode."""
+    return os.environ.get("TEST_MODE") == "true" or os.environ.get("PYTEST_CURRENT_TEST") is not None
+
+
+def _safe_progress_display(display_console: Console) -> bool:
+    """
+    Check if it's safe to create a Progress display.
+
+    Returns True if Progress can be created, False if it should be skipped.
+    """
+    # Always skip in test mode
+    if _is_test_mode():
+        return False
+
+    # Try to detect if a Progress is already active by checking console state
+    # This is a best-effort check - we'll catch LiveError if it fails
+    try:
+        # Rich stores active Live displays in Console._live
+        if hasattr(display_console, "_live") and display_console._live is not None:
+            return False
+    except Exception:
+        pass
+
+    return True
+
+
+def create_progress_callback(progress: Progress, task_id: Any, prefix: str = "") -> Callable[[int, int, str], None]:
+    """
+    Create a standardized progress callback function.
+
+    Args:
+        progress: Rich Progress instance
+        task_id: Task ID from progress.add_task()
+        prefix: Optional prefix for progress messages (e.g., "Loading", "Saving")
+
+    Returns:
+        Callback function that updates progress with n/m counter format
+    """
+
+    def callback(current: int, total: int, artifact: str) -> None:
+        """Update progress with n/m counter format."""
+        if prefix:
+            description = f"{prefix} artifact {current}/{total}: {artifact}"
+        else:
+            description = f"Processing artifact {current}/{total}: {artifact}"
+        progress.update(task_id, description=description)
+
+    return callback
+
+
+def load_bundle_with_progress(
+    bundle_dir: Path,
+    validate_hashes: bool = False,
+    console_instance: Console | None = None,
+) -> ProjectBundle:
+    """
+    Load project bundle with unified progress display.
+
+    Uses consistent n/m counter format: "Loading artifact 3/12: FEATURE-001.yaml"
+    Includes timing information showing elapsed time.
+
+    Args:
+        bundle_dir: Path to bundle directory
+        validate_hashes: Whether to validate file checksums
+        console_instance: Optional Console instance (defaults to module console)
+
+    Returns:
+        Loaded ProjectBundle instance
+    """
+    display_console = console_instance or console
+    start_time = time()
+
+    # Try to use Progress display, but fall back to direct load if it fails
+    # (e.g., if another Progress is already active)
+    use_progress = _safe_progress_display(display_console)
+
+    if use_progress:
+        try:
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                TimeElapsedColumn(),
+                console=display_console,
+            ) as progress:
+                task = progress.add_task("Loading project bundle...", total=None)
+
+                progress_callback = create_progress_callback(progress, task, prefix="Loading")
+
+                bundle = load_project_bundle(
+                    bundle_dir,
+                    validate_hashes=validate_hashes,
+                    progress_callback=progress_callback,
+                )
+                elapsed = time() - start_time
+                progress.update(task, description=f"✓ Bundle loaded ({elapsed:.2f}s)")
+            return bundle
+        except Exception:
+            # If Progress creation fails (e.g., LiveError), fall back to direct load
+            pass
+
+    # No progress display - just load directly
+    return load_project_bundle(
+        bundle_dir,
+        validate_hashes=validate_hashes,
+        progress_callback=None,
+    )
+
+
+def save_bundle_with_progress(
+    bundle: ProjectBundle,
+    bundle_dir: Path,
+    atomic: bool = True,
+    console_instance: Console | None = None,
+) -> None:
+    """
+    Save project bundle with unified progress display.
+
+    Uses consistent n/m counter format: "Saving artifact 3/12: FEATURE-001.yaml"
+    Includes timing information showing elapsed time.
+
+    Args:
+        bundle: ProjectBundle instance to save
+        bundle_dir: Path to bundle directory
+        atomic: Whether to use atomic writes
+        console_instance: Optional Console instance (defaults to module console)
+    """
+    display_console = console_instance or console
+    start_time = time()
+
+    # Try to use Progress display, but fall back to direct save if it fails
+    # (e.g., if another Progress is already active)
+    use_progress = _safe_progress_display(display_console)
+
+    if use_progress:
+        try:
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                TimeElapsedColumn(),
+                console=display_console,
+            ) as progress:
+                task = progress.add_task("Saving project bundle...", total=None)
+
+                progress_callback = create_progress_callback(progress, task, prefix="Saving")
+
+                save_project_bundle(bundle, bundle_dir, atomic=atomic, progress_callback=progress_callback)
+                elapsed = time() - start_time
+                progress.update(task, description=f"✓ Bundle saved ({elapsed:.2f}s)")
+            return
+        except Exception:
+            # If Progress creation fails (e.g., LiveError), fall back to direct save
+            pass
+
+    # No progress display - just save directly
+    save_project_bundle(bundle, bundle_dir, atomic=atomic, progress_callback=None)

specfact_cli-0.11.4/resources/prompts/specfact.03-review.md

@@ -1,112 +0,0 @@
----
-description: Review project bundle to identify ambiguities, resolve gaps, and prepare for promotion.
----
-
-# SpecFact Review Command
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Purpose
-
-Review project bundle to identify/resolve ambiguities and missing information. Asks targeted questions for promotion readiness.
-
-**When to use:** After import/creation, before promotion, when clarification needed.
-
-**Quick:** `/specfact.03-review` (uses active plan) or `/specfact.03-review legacy-api`
-
-## Parameters
-
-### Target/Input
-
-- `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`)
-- `--category CATEGORY` - Focus on specific taxonomy category. Default: None (all categories)
-
-### Output/Results
-
-- `--list-questions` - Output questions in JSON format. Default: False
-- `--list-findings` - Output all findings in structured format. Default: False
-- `--findings-format FORMAT` - Output format: json, yaml, or table. Default: json for non-interactive, table for interactive
-
-### Behavior/Options
-
-- `--no-interactive` - Non-interactive mode (for CI/CD). Default: False (interactive mode)
-- `--answers JSON` - JSON object with question_id -> answer mappings. Default: None
-- `--auto-enrich` - Automatically enrich vague acceptance criteria. Default: False
-
-### Advanced/Configuration
-
-- `--max-questions INT` - Maximum questions per session. Default: 5 (range: 1-10)
-
-## Workflow
-
-### Step 1: Parse Arguments
-
-- Extract bundle name (defaults to active plan if not specified)
-- Extract optional parameters (max-questions, category, etc.)
-
-### Step 2: Execute CLI
-
-```bash
-specfact plan review [<bundle-name>] [--max-questions <n>] [--category <category>] [--list-questions] [--list-findings] [--answers JSON]
-# Uses active plan if bundle not specified
-```
-
-### Step 3: Present Results
-
-- Display Q&A, sections touched, coverage summary (initial/updated)
-- Note: Clarifications don't affect hash (stable across review sessions)
-
-## CLI Enforcement
-
-**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
-
-**Rules:** Execute CLI first, use `--no-interactive` in CI/CD, never modify `.specfact/` directly, use CLI output as grounding.
-
-## Expected Output
-
-### Success
-
-```text
-✓ Review complete: 5 question(s) answered
-
-Project Bundle: legacy-api
-Questions Asked: 5
-
-Sections Touched:
-  • idea.narrative
-  • features[FEATURE-001].acceptance
-  • features[FEATURE-002].outcomes
-
-Coverage Summary:
-  ✅ Functional Scope: clear
-  ✅ Technical Constraints: clear
-  ⚠️ Business Context: partial
-```
-
-### Error (Missing Bundle)
-
-```text
-✗ Project bundle 'legacy-api' not found
-Create one with: specfact plan init legacy-api
-```
-
-## Common Patterns
-
-```bash
-/specfact.03-review                                    # Uses active plan
-/specfact.03-review legacy-api                         # Specific bundle
-/specfact.03-review --max-questions 3                  # Limit questions
-/specfact.03-review --category "Functional Scope"      # Focus category
-/specfact.03-review --list-questions                   # JSON output
-/specfact.03-review --auto-enrich                     # Auto-enrichment
-```
-
-## Context
-
-{ARGS}