specfact-cli 0.14.0__tar.gz → 0.15.0__tar.gz

{specfact_cli-0.14.0 → specfact_cli-0.15.0}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.14.0"
+version = "0.15.0"
 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.0 → specfact_cli-0.15.0}/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.0 → specfact_cli-0.15.0}/resources/prompts/specfact.03-review.md

@@ -37,7 +37,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
 
@@ -260,16 +260,21 @@ 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**:
+3. **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
+4. **Create enrichment report** (for business context, confidence adjustments, missing features): Write Markdown file addressing findings
+5. **Apply manual 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
+6. **Verify**: Run `plan review` again to confirm improvements
 
 ## Context
 

{specfact_cli-0.14.0 → specfact_cli-0.15.0}/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.0 → specfact_cli-0.15.0}/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.0 → specfact_cli-0.15.0}/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.0 → specfact_cli-0.15.0}/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.0 → specfact_cli-0.15.0}/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.14.0"
+__version__ = "0.14.2"

{specfact_cli-0.14.0 → specfact_cli-0.15.0}/src/specfact_cli/__init__.py

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

{specfact_cli-0.14.0 → specfact_cli-0.15.0}/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.0 → specfact_cli-0.15.0}/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.0 → specfact_cli-0.15.0}/src/specfact_cli/cli.py

@@ -72,6 +72,7 @@ from specfact_cli.commands import (
     sync,
 )
 from specfact_cli.modes import OperationalMode, detect_mode
+from specfact_cli.utils.progressive_disclosure import ProgressiveDisclosureGroup
 from specfact_cli.utils.structured_io import StructuredFormat
 
 
@@ -120,7 +121,8 @@ app = typer.Typer(
     help="SpecFact CLI - Spec → Contract → Sentinel for Contract-Driven Development",
     add_completion=True,  # Enable Typer's built-in completion (works natively for bash/zsh/fish without extensions)
     rich_markup_mode="rich",
-    context_settings={"help_option_names": ["-h", "--help"]},  # Add -h as alias for --help
+    context_settings={"help_option_names": ["-h", "--help", "--help-advanced", "-ha"]},  # Add aliases for help
+    cls=ProgressiveDisclosureGroup,  # Use custom group for progressive disclosure
 )
 
 console = Console()
@@ -352,6 +354,11 @@ app.add_typer(
 
 def cli_main() -> None:
     """Entry point for the CLI application."""
+    # Intercept --help-advanced before Typer processes it
+    from specfact_cli.utils.progressive_disclosure import intercept_help_advanced
+
+    intercept_help_advanced()
+
     # Normalize shell names in argv for Typer's built-in completion commands
     normalize_shell_in_argv()
 

{specfact_cli-0.14.0 → specfact_cli-0.15.0}/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":

{specfact_cli-0.14.0 → specfact_cli-0.15.0}/src/specfact_cli/commands/generate.py

@@ -59,7 +59,7 @@ def generate_contracts(
     sdd: Path | None = typer.Option(
         None,
         "--sdd",
-        help="Path to SDD manifest. Default: .specfact/sdd/<bundle-name>.yaml if --bundle specified, else .specfact/sdd.yaml. Ignored if --bundle is specified.",
+        help="Path to SDD manifest. Default: bundle-specific .specfact/projects/<bundle-name>/sdd.yaml if --bundle specified (Phase 8.5), else .specfact/sdd.yaml. Ignored if --bundle is specified.",
     ),
     plan: Path | None = typer.Option(
         None,
@@ -149,7 +149,7 @@ def generate_contracts(
                     # Detect bundle format to determine SDD path
                     format_type, _ = detect_bundle_format(plan_path)
                     if format_type == BundleFormat.MODULAR:
-                        # Modular bundle: SDD is at .specfact/sdd/<bundle-name>.yaml
+                        # Modular bundle: SDD is at .specfact/projects/<bundle-name>/sdd.yaml (Phase 8.5)
                         if plan_path.is_dir():
                             bundle_name = plan_path.name
                         else:
@@ -321,6 +321,7 @@ def generate_contracts_prompt(
         None,
         "--output",
         help=("Output file path (currently unused, prompt saved to .specfact/prompts/)"),
+        hidden=True,  # Hidden by default, shown with --help-advanced
     ),
 ) -> None:
     """
@@ -1360,7 +1361,7 @@ def generate_tasks(
     out: Path | None = typer.Option(
         None,
         "--out",
-        help="Output file path. Default: .specfact/tasks/<bundle-name>-<hash>.tasks.<format>",
+        help="Output file path. Default: bundle-specific .specfact/projects/<bundle-name>/tasks.yaml (Phase 8.5)",
     ),
     # Behavior/Options
     no_interactive: bool = typer.Option(
@@ -1452,17 +1453,20 @@ def generate_tasks(
             print_info("Generating task breakdown...")
             task_list = generate_tasks_func(project_bundle, sdd_manifest, bundle)
 
-            # Determine output path
+            # Determine output path (Phase 8.5: bundle-specific location)
             if out is None:
-                tasks_dir = base_path / SpecFactStructure.TASKS
-                tasks_dir.mkdir(parents=True, exist_ok=True)
+                # Use bundle-specific tasks path (Phase 8.5)
+                out = SpecFactStructure.get_bundle_tasks_path(bundle_name=bundle, base_path=base_path)
+                # Ensure parent directory exists
+                out.parent.mkdir(parents=True, exist_ok=True)
+                # Update extension if needed
                 format_ext = output_format.lower()
-                hash_short = (
-                    task_list.plan_bundle_hash[:16]
-                    if len(task_list.plan_bundle_hash) > 16
-                    else task_list.plan_bundle_hash
-                )
-                out = tasks_dir / f"{bundle}-{hash_short}.tasks.{format_ext}"
+                if format_ext == "yaml":
+                    out = out.with_suffix(".yaml")
+                elif format_ext == "json":
+                    out = out.with_suffix(".json")
+                else:
+                    out = out.with_suffix(".md")
             else:
                 # Ensure correct extension
                 if output_format.lower() == "yaml":

{specfact_cli-0.14.0 → specfact_cli-0.15.0}/src/specfact_cli/commands/implement.py

@@ -70,9 +70,9 @@ def implement_tasks(
     - **Behavior/Options**: --dry-run, --skip-validation, --no-interactive
 
     **Examples:**
-        specfact implement tasks .specfact/tasks/bundle-abc123.tasks.yaml
-        specfact implement tasks .specfact/tasks/bundle-abc123.tasks.yaml --phase setup
-        specfact implement tasks .specfact/tasks/bundle-abc123.tasks.yaml --task TASK-001 --dry-run
+        specfact implement tasks .specfact/projects/bundle-name/tasks.yaml
+        specfact implement tasks .specfact/projects/bundle-name/tasks.yaml --phase setup
+        specfact implement tasks .specfact/projects/bundle-name/tasks.yaml --task TASK-001 --dry-run
     """
     from specfact_cli.telemetry import telemetry