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

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.11.4"
+version = "0.12.1"
 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.12.1/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.12.1}/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.12.1"

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

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

{specfact_cli-0.11.4 → specfact_cli-0.12.1}/src/specfact_cli/analyzers/code_analyzer.py

@@ -175,9 +175,13 @@ class CodeAnalyzer:
             files_to_analyze = [f for f in python_files if not self._should_skip_file(f)]
 
             # Process files in parallel
-            max_workers = max(
-                1, min(os.cpu_count() or 4, 8, len(files_to_analyze))
-            )  # Cap at 8 workers, ensure at least 1
+            # In test mode, use fewer workers to avoid resource contention
+            if os.environ.get("TEST_MODE") == "true":
+                max_workers = max(1, min(2, len(files_to_analyze)))  # Max 2 workers in test mode
+            else:
+                max_workers = max(
+                    1, min(os.cpu_count() or 4, 8, len(files_to_analyze))
+                )  # Cap at 8 workers, ensure at least 1
             completed_count = 0
 
             def analyze_file_safe(file_path: Path) -> dict[str, Any]:
@@ -185,58 +189,76 @@ class CodeAnalyzer:
                 return self._analyze_file_parallel(file_path)
 
             if files_to_analyze:
-                executor = ThreadPoolExecutor(max_workers=max_workers)
-                interrupted = False
-                try:
-                    # Submit all tasks
-                    future_to_file = {executor.submit(analyze_file_safe, f): f for f in files_to_analyze}
-
-                    # Collect results as they complete
+                # In test mode, use sequential processing to avoid ThreadPoolExecutor deadlocks
+                is_test_mode = os.environ.get("TEST_MODE") == "true"
+                if is_test_mode:
+                    # Sequential processing in test mode - avoids ThreadPoolExecutor deadlocks entirely
+                    for file_path in files_to_analyze:
+                        try:
+                            results = analyze_file_safe(file_path)
+                            self._merge_analysis_results(results)
+                            completed_count += 1
+                            progress.update(task3, completed=completed_count)
+                        except Exception as e:
+                            console.print(f"[dim]⚠ Warning: Failed to analyze {file_path}: {e}[/dim]")
+                            completed_count += 1
+                            progress.update(task3, completed=completed_count)
+                else:
+                    executor = ThreadPoolExecutor(max_workers=max_workers)
+                    interrupted = False
+                    # In test mode, use wait=False to avoid hanging on shutdown
+                    wait_on_shutdown = not is_test_mode
                     try:
-                        for future in as_completed(future_to_file):
-                            try:
-                                results = future.result()
-                                # Merge results into instance variables (sequential merge is fast)
-                                self._merge_analysis_results(results)
-                                completed_count += 1
-                                progress.update(task3, completed=completed_count)
-                            except KeyboardInterrupt:
-                                # Cancel remaining tasks and break out of loop immediately
-                                interrupted = True
-                                for f in future_to_file:
-                                    if not f.done():
-                                        f.cancel()
-                                break
-                            except Exception as e:
-                                # Log error but continue processing
-                                file_path = future_to_file[future]
-                                console.print(f"[dim]⚠ Warning: Failed to analyze {file_path}: {e}[/dim]")
-                                completed_count += 1
-                                progress.update(task3, completed=completed_count)
+                        # Submit all tasks
+                        future_to_file = {executor.submit(analyze_file_safe, f): f for f in files_to_analyze}
+
+                        # Collect results as they complete
+                        try:
+                            for future in as_completed(future_to_file):
+                                try:
+                                    results = future.result()
+                                    # Merge results into instance variables (sequential merge is fast)
+                                    self._merge_analysis_results(results)
+                                    completed_count += 1
+                                    progress.update(task3, completed=completed_count)
+                                except KeyboardInterrupt:
+                                    # Cancel remaining tasks and break out of loop immediately
+                                    interrupted = True
+                                    for f in future_to_file:
+                                        if not f.done():
+                                            f.cancel()
+                                    break
+                                except Exception as e:
+                                    # Log error but continue processing
+                                    file_path = future_to_file[future]
+                                    console.print(f"[dim]⚠ Warning: Failed to analyze {file_path}: {e}[/dim]")
+                                    completed_count += 1
+                                    progress.update(task3, completed=completed_count)
+                        except KeyboardInterrupt:
+                            # Also catch KeyboardInterrupt from as_completed() itself
+                            interrupted = True
+                            for f in future_to_file:
+                                if not f.done():
+                                    f.cancel()
+
+                        # If interrupted, re-raise KeyboardInterrupt after breaking out of loop
+                        if interrupted:
+                            raise KeyboardInterrupt
                     except KeyboardInterrupt:
-                        # Also catch KeyboardInterrupt from as_completed() itself
+                        # Gracefully shutdown executor on interrupt (cancel pending tasks, don't wait)
                         interrupted = True
-                        for f in future_to_file:
-                            if not f.done():
-                                f.cancel()
-
-                    # If interrupted, re-raise KeyboardInterrupt after breaking out of loop
-                    if interrupted:
-                        raise KeyboardInterrupt
-                except KeyboardInterrupt:
-                    # Gracefully shutdown executor on interrupt (cancel pending tasks, don't wait)
-                    interrupted = True
-                    executor.shutdown(wait=False, cancel_futures=True)
-                    raise
-                finally:
-                    # Ensure executor is properly shutdown
-                    # If interrupted, don't wait for tasks (they're already cancelled)
-                    # shutdown() is safe to call multiple times
-                    if not interrupted:
-                        executor.shutdown(wait=True)
-                    else:
-                        # Already shutdown with wait=False, just ensure cleanup
-                        executor.shutdown(wait=False)
+                        executor.shutdown(wait=False, cancel_futures=True)
+                        raise
+                    finally:
+                        # Ensure executor is properly shutdown
+                        # If interrupted, don't wait for tasks (they're already cancelled)
+                        # shutdown() is safe to call multiple times
+                        # In test mode, use wait=False to avoid hanging
+                        if not interrupted:
+                            executor.shutdown(wait=wait_on_shutdown)
+                        else:
+                            # Already shutdown with wait=False, just ensure cleanup
+                            executor.shutdown(wait=False)
 
             # Update progress for skipped files
             skipped_count = len(python_files) - len(files_to_analyze)

{specfact_cli-0.11.4 → specfact_cli-0.12.1}/src/specfact_cli/analyzers/graph_analyzer.py

@@ -149,11 +149,17 @@ class GraphAnalyzer:
 
         # Add edges from AST imports (parallelized for performance)
         import multiprocessing
+
+        # In test mode, use fewer workers to avoid resource contention
+        import os
         from concurrent.futures import ThreadPoolExecutor, as_completed
 
-        max_workers = max(
-            1, min(multiprocessing.cpu_count() or 4, 16, len(python_files))
-        )  # Increased for faster processing, ensure at least 1
+        if os.environ.get("TEST_MODE") == "true":
+            max_workers = max(1, min(2, len(python_files)))  # Max 2 workers in test mode
+        else:
+            max_workers = max(
+                1, min(multiprocessing.cpu_count() or 4, 16, len(python_files))
+            )  # Increased for faster processing, ensure at least 1
 
         # Get list of known modules for matching (needed for parallel processing)
         known_modules = list(graph.nodes())
@@ -176,8 +182,12 @@ class GraphAnalyzer:
             return edges
 
         # Process AST imports in parallel
-        with ThreadPoolExecutor(max_workers=max_workers) as executor:
-            future_to_file = {executor.submit(process_imports, file_path): file_path for file_path in python_files}
+        import os
+
+        executor1 = ThreadPoolExecutor(max_workers=max_workers)
+        wait_on_shutdown = os.environ.get("TEST_MODE") != "true"
+        try:
+            future_to_file = {executor1.submit(process_imports, file_path): file_path for file_path in python_files}
 
             for future in as_completed(future_to_file):
                 try:
@@ -186,11 +196,14 @@ class GraphAnalyzer:
                         graph.add_edge(module_name, matching_module)
                 except Exception:
                     continue
+        finally:
+            executor1.shutdown(wait=wait_on_shutdown)
 
         # Extract call graphs using pyan (if available) - parallelized for performance
-        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        executor2 = ThreadPoolExecutor(max_workers=max_workers)
+        try:
             future_to_file = {
-                executor.submit(self.extract_call_graph, file_path): file_path for file_path in python_files
+                executor2.submit(self.extract_call_graph, file_path): file_path for file_path in python_files
             }
 
             for future in as_completed(future_to_file):
@@ -206,6 +219,8 @@ class GraphAnalyzer:
                 except Exception:
                     # Skip if call graph extraction fails for this file
                     continue
+        finally:
+            executor2.shutdown(wait=wait_on_shutdown)
 
         self.dependency_graph = graph
         return graph

{specfact_cli-0.11.4 → specfact_cli-0.12.1}/src/specfact_cli/analyzers/relationship_mapper.py

@@ -380,10 +380,16 @@ class RelationshipMapper:
             }
 
         # Use ThreadPoolExecutor for parallel processing
-        max_workers = min(os.cpu_count() or 4, 16, len(python_files))  # Cap at 16 workers for faster processing
+        # In test mode, use fewer workers to avoid resource contention
+        if os.environ.get("TEST_MODE") == "true":
+            max_workers = max(1, min(2, len(python_files)))  # Max 2 workers in test mode
+        else:
+            max_workers = min(os.cpu_count() or 4, 16, len(python_files))  # Cap at 16 workers for faster processing
 
         executor = ThreadPoolExecutor(max_workers=max_workers)
         interrupted = False
+        # In test mode, use wait=False to avoid hanging on shutdown
+        wait_on_shutdown = os.environ.get("TEST_MODE") != "true"
         try:
             # Submit all tasks
             future_to_file = {executor.submit(self._analyze_file_parallel, f): f for f in python_files}
@@ -424,7 +430,7 @@ class RelationshipMapper:
             raise
         finally:
             if not interrupted:
-                executor.shutdown(wait=True)
+                executor.shutdown(wait=wait_on_shutdown)
             else:
                 executor.shutdown(wait=False)