specfact-cli 0.14.2__tar.gz → 0.15.1__tar.gz

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.14.2
+Version: 0.15.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.14.2 → specfact_cli-0.15.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.14.2"
+version = "0.15.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.14.2 → specfact_cli-0.15.1}/resources/prompts/specfact.01-import.md

@@ -20,7 +20,7 @@ Import codebase → plan bundle. CLI extracts routes/schemas/relationships/contr
 
 **Target/Input**: `--bundle NAME` (optional, defaults to active plan), `--repo PATH`, `--entry-point PATH`, `--enrichment PATH`  
 **Output/Results**: `--report PATH`  
-**Behavior/Options**: `--shadow-only`, `--enrich-for-speckit`  
+**Behavior/Options**: `--shadow-only`, `--enrich-for-speckit/--no-enrich-for-speckit` (default: enabled, uses PlanEnricher for consistent enrichment)  
 **Advanced/Configuration**: `--confidence FLOAT` (0.0-1.0), `--key-format FORMAT` (classname|sequential)
 
 ## Workflow
@@ -28,12 +28,14 @@ Import codebase → plan bundle. CLI extracts routes/schemas/relationships/contr
 1. **Execute CLI**: `specfact import from-code [<bundle>] --repo <path> [options]`
    - CLI extracts: routes (FastAPI/Flask/Django), schemas (Pydantic), relationships, contracts (OpenAPI scaffolds), source tracking
    - Uses active plan if bundle not specified
+   - **Auto-enrichment enabled by default**: Automatically enhances vague acceptance criteria, incomplete requirements, and generic tasks using PlanEnricher (same logic as `plan review --auto-enrich`)
+   - Use `--no-enrich-for-speckit` to disable auto-enrichment
 
 2. **LLM Enrichment** (if `--enrichment` provided):
    - Read `.specfact/projects/<bundle>/enrichment_context.md`
    - Enrich: business context, "why" reasoning, missing acceptance criteria
    - Validate: contracts vs code, feature/story alignment
-   - Save enrichment report to `.specfact/reports/enrichment/` (if created)
+   - Save enrichment report to `.specfact/projects/<bundle-name>/reports/enrichment/` (bundle-specific, Phase 8.5, if created)
 
 3. **Present**: Bundle location, report path, summary (features/stories/contracts/relationships)
 
@@ -86,7 +88,7 @@ specfact import from-code [<bundle>] --repo <path> --no-interactive
 - ❌ Write to `.specfact/` folder directly (always use CLI)
 - ❌ Use direct file manipulation tools for writing (use CLI commands)
 
-**Output**: Generate enrichment report (Markdown) saved to `.specfact/reports/enrichment/`
+**Output**: Generate enrichment report (Markdown) saved to `.specfact/projects/<bundle-name>/reports/enrichment/` (bundle-specific, Phase 8.5)
 
 ### Phase 3: CLI Artifact Creation (REQUIRED)
 
@@ -107,8 +109,9 @@ specfact import from-code [<bundle>] --repo <path> --enrichment <enrichment-repo
 ## Common Patterns
 
 ```bash
-/specfact.01-import --repo .                    # Uses active plan
-/specfact.01-import --bundle legacy-api --repo .
+/specfact.01-import --repo .                    # Uses active plan, auto-enrichment enabled by default
+/specfact.01-import --bundle legacy-api --repo . # Auto-enrichment enabled
+/specfact.01-import --repo . --no-enrich-for-speckit  # Disable auto-enrichment
 /specfact.01-import --repo . --entry-point src/auth/
 /specfact.01-import --repo . --enrichment report.md
 ```

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/resources/prompts/specfact.03-review.md

@@ -30,6 +30,7 @@ Review project bundle to identify/resolve ambiguities and missing information. A
 ### Output/Results
 
 - `--list-questions` - Output questions in JSON format. Default: False
+- `--output-questions PATH` - Save questions directly to file (JSON format). Use with `--list-questions` to save instead of stdout. Default: None
 - `--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
 
@@ -37,7 +38,7 @@ Review project bundle to identify/resolve ambiguities and missing information. A
 
 - `--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
+- `--auto-enrich` - Automatically enrich vague acceptance criteria using PlanEnricher (same enrichment logic as `import from-code`). Default: False (opt-in for review, but import has auto-enrichment enabled by default)
 
 ### Advanced/Configuration
 
@@ -55,11 +56,15 @@ Review project bundle to identify/resolve ambiguities and missing information. A
 **First, get findings to understand what needs enrichment:**
 
 ```bash
-specfact plan review [<bundle-name>] --list-findings --findings-format json
+# Get findings (saves to stdout - can redirect to file)
+specfact plan review [<bundle-name>] --list-findings --findings-format json --no-interactive > findings.json
+
+# Or get questions and save directly to file (recommended)
+specfact plan review [<bundle-name>] --list-questions --output-questions questions.json --no-interactive
 # Uses active plan if bundle not specified
 ```
 
-This outputs all ambiguities and missing information in structured format.
+**Note**: The `--output-questions` option saves questions directly to a file, avoiding the need for complex JSON parsing. The ambiguity scanner now recognizes the simplified format (e.g., "Must verify X works correctly (see contract examples)") as valid and will not flag it as vague.
 
 ### Step 3: Create Enrichment Report (if needed)
 
@@ -115,7 +120,38 @@ FEATURE-OTHER → 0.8
 
 #### Option A: Use enrichment to answer review questions
 
-Create answers JSON from enrichment report and use with review:
+**Recommended workflow:**
+
+1. **Get questions and save to file:**
+
+   ```bash
+   specfact plan review [<bundle-name>] --list-questions --output-questions questions.json --no-interactive
+   ```
+
+2. **Edit the JSON file** to add answers:
+
+   ```json
+   {
+     "questions": [...],
+     "total": 5,
+     "answers": {
+       "Q001": "Answer for question 1",
+       "Q002": "Answer for question 2"
+     }
+   }
+   ```
+
+3. **Extract answers and provide to CLI:**
+
+   ```bash
+   # Extract answers from file (simple approach)
+   specfact plan review [<bundle-name>] --answers "$(jq -c '.answers' questions.json)" --no-interactive
+   
+   # Or provide answers directly
+   specfact plan review [<bundle-name>] --answers '{"Q001": "answer1", "Q002": "answer2"}' --no-interactive
+   ```
+
+**Alternative**: Create answers JSON from enrichment report:
 
 ```bash
 specfact plan review [<bundle-name>] --answers '{"Q001": "answer1", "Q002": "answer2"}'
@@ -139,7 +175,10 @@ specfact import from-code [<bundle-name>] --repo . --enrichment enrichment-repor
 
 - **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
+- **CRITICAL**: Never manually edit `.specfact/` files directly - always use CLI commands
+  - This includes `idea.yaml`, `product.yaml`, feature files, story files, etc.
+  - Even if a file doesn't exist yet, use CLI commands to create it (e.g., `plan update-idea` will create `idea.yaml` if needed)
+  - Direct file modification bypasses validation and can cause inconsistencies
 
 ### Step 5: Present Results
 
@@ -155,10 +194,16 @@ specfact import from-code [<bundle-name>] --repo . --enrichment enrichment-repor
 
 - Execute CLI first - never create artifacts directly
 - Use `--no-interactive` flag in CI/CD environments
-- Never modify `.specfact/` directly
+- **NEVER modify `.specfact/` files directly** - always use CLI commands
+  - ❌ **DO NOT** edit `idea.yaml`, `product.yaml`, feature files, or any other artifacts directly
+  - ❌ **DO NOT** create new artifact files manually (even if they don't exist yet)
+  - ✅ **DO** use CLI commands: `plan update-idea`, `plan update-feature`, `plan update-story`, etc.
+  - ✅ **DO** use CLI commands to create new artifacts: `plan init`, `plan add-feature`, etc.
 - Use CLI output as grounding for validation
 - Code generation requires LLM (only via AI IDE slash prompts, not CLI-only)
 
+**Important**: If an artifact file doesn't exist yet, use the appropriate CLI command to create it. Never create or modify `.specfact/` files manually, as this bypasses validation and can cause inconsistencies.
+
 ## Dual-Stack Workflow (Copilot Mode)
 
 When in copilot mode, follow this three-phase workflow:
@@ -166,16 +211,22 @@ When in copilot mode, follow this three-phase workflow:
 ### Phase 1: CLI Grounding (REQUIRED)
 
 ```bash
-# Execute CLI to get structured output
-specfact plan review [<bundle-name>] --list-findings --findings-format json --no-interactive
+# Option 1: Get findings (redirect to file if needed)
+specfact plan review [<bundle-name>] --list-findings --findings-format json --no-interactive > findings.json
+
+# Option 2: Get questions and save directly to file (recommended - avoids JSON parsing)
+specfact plan review [<bundle-name>] --list-questions --output-questions questions.json --no-interactive
 ```
 
 **Capture**:
 
 - CLI-generated findings (ambiguities, missing information)
+- Questions saved directly to file (no complex parsing needed)
 - Structured JSON/YAML output for bulk processing
 - Metadata (timestamps, confidence scores)
 
+**Note**: Use `--output-questions` to save questions directly to a file. This avoids the need for complex on-the-fly Python code to extract JSON from CLI output.
+
 ### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only)
 
 **Purpose**: Add semantic understanding to CLI findings
@@ -189,8 +240,10 @@ specfact plan review [<bundle-name>] --list-findings --findings-format json --no
 
 **What NOT to do**:
 
-- ❌ Create YAML/JSON artifacts directly
+- ❌ Create YAML/JSON artifacts directly (even if they don't exist yet)
 - ❌ Modify CLI artifacts directly (use CLI commands to update)
+- ❌ Edit `idea.yaml`, `product.yaml`, feature files, or story files manually
+- ❌ Create new artifact files manually - use CLI commands instead
 - ❌ Bypass CLI validation
 - ❌ Write to `.specfact/` folder directly (always use CLI)
 
@@ -252,7 +305,8 @@ Create one with: specfact plan init legacy-api
 
 # Non-interactive with answers
 /specfact.03-review --answers '{"Q001": "answer"}'     # Provide answers directly
-/specfact.03-review --list-questions                   # Output questions as JSON
+/specfact.03-review --list-questions                   # Output questions as JSON to stdout
+/specfact.03-review --list-questions --output-questions questions.json  # Save questions to file
 
 # Auto-enrichment
 /specfact.03-review --auto-enrich                     # Auto-enrich vague criteria
@@ -260,16 +314,38 @@ Create one with: specfact plan init legacy-api
 
 ## Enrichment Workflow
 
+**Note**: Import command (`specfact import from-code`) has **auto-enrichment enabled by default** using PlanEnricher. Review command requires explicit `--auto-enrich` flag.
+
 **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`
+1. **Get questions** (save to file for easy editing):
+
+   ```bash
+   specfact plan review --list-questions --output-questions questions.json --no-interactive
+   ```
+
+2. **Get findings** (optional, for comprehensive analysis):
+
+   ```bash
+   specfact plan review --list-findings --findings-format json --no-interactive > findings.json
+   ```
+
+3. **Analyze findings**: Review missing information (target_users, value_hypothesis, etc.)
+
+4. **Apply automatic enrichment** (if needed):
+
+   - **During import**: Auto-enrichment happens automatically (enabled by default)
+   - **After import**: Use `specfact plan review --auto-enrich` to enhance vague criteria
+   - **Note**: The scanner now recognizes simplified format (e.g., "Must verify X works correctly (see contract examples)") as valid
+
+5. **Create enrichment report** (for business context, confidence adjustments, missing features): Write Markdown file addressing findings
+
+6. **Apply manual enrichment**:
+   - **Preferred**: Edit `questions.json` file to add answers, then use `--answers` with the file
    - **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
+
+7. **Verify**: Run `plan review` again to confirm improvements
 
 ## Context
 

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/resources/prompts/specfact.04-sdd.md

@@ -25,7 +25,7 @@ Create/update SDD manifest from project bundle. Captures WHY (intent/constraints
 ### Target/Input
 
 - `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`)
-- `--sdd PATH` - Output SDD manifest path. Default: .specfact/sdd/<bundle-name>.<format>
+- `--sdd PATH` - Output SDD manifest path. Default: bundle-specific .specfact/projects/<bundle-name>/sdd.<format> (Phase 8.5)
 
 ### Output/Results
 
@@ -119,12 +119,12 @@ specfact plan harden [<bundle-name>] --no-interactive
 ### Success
 
 ```text
-✓ SDD manifest created: .specfact/sdd/legacy-api.yaml
+✓ SDD manifest created: .specfact/projects/legacy-api/sdd.yaml
 
 SDD Manifest Summary:
 Project Bundle: .specfact/projects/legacy-api/
 Bundle Hash: abc123def456...
-SDD Path: .specfact/sdd/legacy-api.yaml
+SDD Path: .specfact/projects/legacy-api/sdd.yaml
 
 WHY (Intent):
   Build secure authentication system
@@ -151,7 +151,7 @@ Create one with: specfact plan init legacy-api
 /specfact.04-sdd                              # Uses active plan
 /specfact.04-sdd legacy-api                   # Specific bundle
 /specfact.04-sdd --output-format json         # JSON format
-/specfact.04-sdd --sdd .specfact/sdd/custom.yaml
+/specfact.04-sdd --sdd .specfact/projects/custom-bundle/sdd.yaml
 ```
 
 ## Context

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/resources/prompts/specfact.05-enforce.md

@@ -25,12 +25,12 @@ Validate SDD manifest against project bundle and contracts. Checks hash matching
 ### Target/Input
 
 - `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`)
-- `--sdd PATH` - Path to SDD manifest. Default: .specfact/sdd/<bundle-name>.<format>
+- `--sdd PATH` - Path to SDD manifest. Default: bundle-specific .specfact/projects/<bundle-name>/sdd.<format> (Phase 8.5), with fallback to legacy .specfact/sdd/<bundle-name>.<format>
 
 ### Output/Results
 
 - `--output-format FORMAT` - Output format (yaml, json, markdown). Default: yaml
-- `--out PATH` - Output file path. Default: .specfact/reports/sdd/validation-<timestamp>.<format>
+- `--out PATH` - Output file path. Default: bundle-specific .specfact/projects/<bundle-name>/reports/enforcement/report-<timestamp>.<format> (Phase 8.5)
 
 ### Behavior/Options
 
@@ -131,7 +131,7 @@ Total deviations: 0
   Medium: 0
   Low: 0
 
-Report saved to: .specfact/reports/sdd/validation-2025-11-26T10-30-00.yaml
+Report saved to: .specfact/projects/<bundle-name>/reports/enforcement/report-2025-11-26T10-30-00.yaml
 ```
 
 ### Failure (Hash Mismatch)

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/resources/prompts/specfact.compare.md

@@ -31,7 +31,7 @@ Compare two project bundles (or legacy plan bundles) to detect deviations, misma
 ### Output/Results
 
 - `--output-format FORMAT` - Output format (markdown, json, yaml). Default: markdown
-- `--out PATH` - Output file path. Default: .specfact/reports/comparison/deviations-<timestamp>.md
+- `--out PATH` - Output file path. Default: bundle-specific .specfact/projects/<bundle-name>/reports/comparison/report-<timestamp>.md (Phase 8.5), or global .specfact/reports/comparison/ if no bundle context
 
 ### Behavior/Options
 
@@ -125,7 +125,7 @@ specfact plan compare [--bundle <name>] --no-interactive
 ```text
 ✓ Comparison complete
 
-Comparison Report: .specfact/reports/comparison/deviations-2025-11-26T10-30-00.md
+Comparison Report: .specfact/projects/<bundle-name>/reports/comparison/report-2025-11-26T10-30-00.md
 
 Deviations Summary:
   Total: 5

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/resources/prompts/specfact.validate.md

@@ -28,7 +28,7 @@ Run full validation suite for reproducibility and contract compliance. Executes
 
 ### Output/Results
 
-- `--out PATH` - Output report path. Default: .specfact/reports/enforcement/report-<timestamp>.yaml
+- `--out PATH` - Output report path. Default: bundle-specific .specfact/projects/<bundle-name>/reports/enforcement/report-<timestamp>.yaml (Phase 8.5), or global .specfact/reports/enforcement/ if no bundle context
 
 ### Behavior/Options
 
@@ -135,7 +135,7 @@ Check Summary:
   Property Tests        ✓ Passed
   Smoke Tests           ✓ Passed
 
-Report saved to: .specfact/reports/enforcement/report-2025-11-26T10-30-00.yaml
+Report saved to: .specfact/projects/<bundle-name>/reports/enforcement/report-2025-11-26T10-30-00.yaml
 ```
 
 ### Failure

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/src/specfact_cli/__init__.py

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

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/src/specfact_cli/analyzers/ambiguity_scanner.py

@@ -521,7 +521,11 @@ class AmbiguityScanner:
                 else:
                     # Check for vague acceptance criteria patterns
                     # BUT: Skip if criteria are already code-specific (preserve code-specific criteria from code2spec)
-                    from specfact_cli.utils.acceptance_criteria import is_code_specific_criteria
+                    # AND: Skip if criteria use the new simplified format (post-GWT refactoring)
+                    from specfact_cli.utils.acceptance_criteria import (
+                        is_code_specific_criteria,
+                        is_simplified_format_criteria,
+                    )
 
                     vague_patterns = [
                         "is implemented",
@@ -532,10 +536,16 @@ class AmbiguityScanner:
                         "is ready",
                     ]
 
-                    # Only check criteria that are NOT code-specific
+                    # Only check criteria that are NOT code-specific AND NOT using simplified format
                     # Note: Acceptance criteria are simple text descriptions (not OpenAPI format)
                     # Detailed testable examples are stored in OpenAPI contract files (.openapi.yaml)
-                    non_code_specific_criteria = [acc for acc in story.acceptance if not is_code_specific_criteria(acc)]
+                    # The new simplified format (e.g., "Must verify X works correctly (see contract examples)")
+                    # is VALID and should not be flagged as vague
+                    non_code_specific_criteria = [
+                        acc
+                        for acc in story.acceptance
+                        if not is_code_specific_criteria(acc) and not is_simplified_format_criteria(acc)
+                    ]
 
                     vague_criteria = [
                         acc

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/src/specfact_cli/analyzers/code_analyzer.py

@@ -144,6 +144,8 @@ class CodeAnalyzer:
             SpinnerColumn(),
             TextColumn("[progress.description]{task.description}"),
             BarColumn(),
+            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+            TextColumn("({task.completed}/{task.total})"),
             TimeElapsedColumn(),
             console=console,
         ) as progress:
@@ -202,7 +204,13 @@ class CodeAnalyzer:
                             prev_features_count = len(self.features)
                             self._merge_analysis_results(results)
                             completed_count += 1
-                            progress.update(task3, completed=completed_count)
+                            # Update progress with feature count in description
+                            features_count = len(self.features)
+                            progress.update(
+                                task3,
+                                completed=completed_count,
+                                description=f"[cyan]Phase 3: Analyzing files and extracting features... ({features_count} features discovered)",
+                            )
 
                             # Phase 4.9: Report incremental results for quick first value
                             if self.incremental_callback and len(self.features) > prev_features_count:
@@ -211,7 +219,12 @@ class CodeAnalyzer:
                         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)
+                            features_count = len(self.features)
+                            progress.update(
+                                task3,
+                                completed=completed_count,
+                                description=f"[cyan]Phase 3: Analyzing files and extracting features... ({features_count} features discovered)",
+                            )
                 else:
                     executor = ThreadPoolExecutor(max_workers=max_workers)
                     interrupted = False
@@ -230,7 +243,13 @@ class CodeAnalyzer:
                                     prev_features_count = len(self.features)
                                     self._merge_analysis_results(results)
                                     completed_count += 1
-                                    progress.update(task3, completed=completed_count)
+                                    # Update progress with feature count in description
+                                    features_count = len(self.features)
+                                    progress.update(
+                                        task3,
+                                        completed=completed_count,
+                                        description=f"[cyan]Phase 3: Analyzing files and extracting features... ({features_count} features discovered)",
+                                    )
 
                                     # Phase 4.9: Report incremental results for quick first value
                                     if self.incremental_callback and len(self.features) > prev_features_count:
@@ -248,7 +267,12 @@ class CodeAnalyzer:
                                     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)
+                                    features_count = len(self.features)
+                                    progress.update(
+                                        task3,
+                                        completed=completed_count,
+                                        description=f"[cyan]Phase 3: Analyzing files and extracting features... ({features_count} features discovered)",
+                                    )
                         except KeyboardInterrupt:
                             # Also catch KeyboardInterrupt from as_completed() itself
                             interrupted = True
@@ -278,7 +302,12 @@ class CodeAnalyzer:
             # Update progress for skipped files
             skipped_count = len(python_files) - len(files_to_analyze)
             if skipped_count > 0:
-                progress.update(task3, completed=len(python_files))
+                features_count = len(self.features)
+                progress.update(
+                    task3,
+                    completed=len(python_files),
+                    description=f"[cyan]Phase 3: Analyzing files and extracting features... ({features_count} features discovered)",
+                )
 
             progress.update(
                 task3,

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/src/specfact_cli/analyzers/control_flow_analyzer.py

@@ -53,7 +53,7 @@ class ControlFlowAnalyzer:
             method_name: Name of the method
 
         Returns:
-            Dictionary with scenario types as keys and lists of Given/When/Then scenarios as values
+            Dictionary with scenario types as keys and lists of scenario descriptions as values
         """
         scenarios: dict[str, list[str]] = {
             "primary": [],
@@ -67,9 +67,7 @@ class ControlFlowAnalyzer:
 
         # If no scenarios found, generate default primary scenario
         if not any(scenarios.values()):
-            scenarios["primary"].append(
-                f"Given {class_name} instance, When {method_name} is called, Then method executes successfully"
-            )
+            scenarios["primary"].append(f"{method_name} executes successfully")
 
         return scenarios
 
@@ -103,15 +101,13 @@ class ControlFlowAnalyzer:
         # Primary scenario: if branch (happy path)
         if if_node.body:
             primary_action = self._extract_action_from_body(if_node.body)
-            scenarios["primary"].append(
-                f"Given {class_name} instance, When {method_name} is called with {condition}, Then {primary_action}"
-            )
+            scenarios["primary"].append(f"{method_name} called with {condition}: {primary_action}")
 
         # Alternate scenario: else branch
         if if_node.orelse:
             alternate_action = self._extract_action_from_body(if_node.orelse)
             scenarios["alternate"].append(
-                f"Given {class_name} instance, When {method_name} is called with {self._negate_condition(condition)}, Then {alternate_action}"
+                f"{method_name} called with {self._negate_condition(condition)}: {alternate_action}"
             )
 
     @beartype
@@ -122,9 +118,7 @@ class ControlFlowAnalyzer:
         # Primary scenario: try block (happy path)
         if try_node.body:
             primary_action = self._extract_action_from_body(try_node.body)
-            scenarios["primary"].append(
-                f"Given {class_name} instance, When {method_name} is called, Then {primary_action}"
-            )
+            scenarios["primary"].append(f"{method_name} executes: {primary_action}")
 
         # Exception scenarios: except blocks
         for handler in try_node.handlers:
@@ -133,22 +127,16 @@ class ControlFlowAnalyzer:
                 exception_type = self._extract_exception_type(handler.type)
 
             exception_action = self._extract_action_from_body(handler.body) if handler.body else "error is handled"
-            scenarios["exception"].append(
-                f"Given {class_name} instance, When {method_name} is called and {exception_type} occurs, Then {exception_action}"
-            )
+            scenarios["exception"].append(f"{method_name} raises {exception_type}: {exception_action}")
 
             # Check for retry/recovery logic in exception handler
             if self._has_retry_logic(handler.body):
-                scenarios["recovery"].append(
-                    f"Given {class_name} instance, When {method_name} fails with {exception_type}, Then system retries and recovers"
-                )
+                scenarios["recovery"].append(f"{method_name} retries and recovers after {exception_type}")
 
         # Recovery scenario: finally block or retry logic
         if try_node.finalbody:
             recovery_action = self._extract_action_from_body(try_node.finalbody)
-            scenarios["recovery"].append(
-                f"Given {class_name} instance, When {method_name} completes or fails, Then {recovery_action}"
-            )
+            scenarios["recovery"].append(f"{method_name} cleanup: {recovery_action}")
 
     @beartype
     def _extract_loop_scenario(
@@ -157,9 +145,7 @@ class ControlFlowAnalyzer:
         """Extract scenario from loop (might indicate retry logic)."""
         # Check if loop contains retry/retry logic
         if self._has_retry_logic(loop_node.body):
-            scenarios["recovery"].append(
-                f"Given {class_name} instance, When {method_name} is called, Then system retries on failure until success"
-            )
+            scenarios["recovery"].append(f"{method_name} retries on failure until success")
 
     @beartype
     def _extract_condition(self, test_node: ast.AST) -> str:

{specfact_cli-0.14.2 → specfact_cli-0.15.1}/src/specfact_cli/commands/enforce.py

@@ -129,7 +129,7 @@ def enforce_sdd(
     sdd: Path | None = typer.Option(
         None,
         "--sdd",
-        help="Path to SDD manifest. Default: .specfact/sdd/<bundle-name>.<format>",
+        help="Path to SDD manifest. Default: bundle-specific .specfact/projects/<bundle-name>/sdd.<format> (Phase 8.5), with fallback to legacy .specfact/sdd/<bundle-name>.<format>",
     ),
     # Output/Results
     output_format: str = typer.Option(
@@ -140,7 +140,7 @@ def enforce_sdd(
     out: Path | None = typer.Option(
         None,
         "--out",
-        help="Output file path. Default: .specfact/reports/sdd/validation-<timestamp>.<format>",
+        help="Output file path. Default: bundle-specific .specfact/projects/<bundle-name>/reports/enforcement/report-<timestamp>.<format> (Phase 8.5)",
     ),
     # Behavior/Options
     no_interactive: bool = typer.Option(
@@ -213,7 +213,8 @@ def enforce_sdd(
         discovered_sdd = find_sdd_for_bundle(bundle, base_path, sdd)
         if discovered_sdd is None:
             console.print("[bold red]✗[/bold red] SDD manifest not found")
-            console.print(f"[dim]Searched for: .specfact/sdd/{bundle}.yaml or .specfact/sdd/{bundle}.json[/dim]")
+            console.print(f"[dim]Searched for: .specfact/projects/{bundle}/sdd.yaml (bundle-specific, Phase 8.5)[/dim]")
+            console.print(f"[dim]Fallback: .specfact/sdd/{bundle}.yaml or .specfact/sdd/{bundle}.json[/dim]")
             console.print("[dim]Legacy fallback: .specfact/sdd.yaml or .specfact/sdd.json[/dim]")
             console.print(f"[dim]Create one with: specfact plan harden {bundle}[/dim]")
             raise typer.Exit(1)
@@ -382,15 +383,15 @@ def enforce_sdd(
                 else:
                     console.print("[dim]No API contracts found in bundle[/dim]")
 
-            # Generate output report
+            # Generate output report (Phase 8.5: bundle-specific location)
             output_format_str = output_format.lower()
             if out is None:
-                SpecFactStructure.ensure_structure()
-                reports_dir = Path(".") / SpecFactStructure.ROOT / "reports" / "sdd"
-                reports_dir.mkdir(parents=True, exist_ok=True)
-                timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+                # Use bundle-specific enforcement report path
                 extension = "md" if output_format_str == "markdown" else output_format_str
-                out = reports_dir / f"validation-{timestamp}.{extension}"
+                out = SpecFactStructure.get_bundle_enforcement_report_path(bundle_name=bundle, base_path=base_path)
+                # Update extension if needed
+                if extension != "yaml" and out.suffix != f".{extension}":
+                    out = out.with_suffix(f".{extension}")
 
             # Save report
             if output_format_str == "markdown":