Promote dev to main: flat command doc alignment

packages/specfact-backlog/module-package.yaml

@@ -1,5 +1,5 @@
 name: nold-ai/specfact-backlog
-version: 0.41.28
+version: 0.41.32
 commands:
   - backlog
 tier: official
@@ -27,5 +27,5 @@ schema_extensions:
   project_metadata:
     - backlog_core.backlog_config
 integrity:
-  checksum: sha256:7aee384a5e0b1b6cf1eaa54e259d35efab0fb38fb4498c171d2fe37b0d6d94c3
-  signature: Sx6pQMGz1pjW3LAnuGtI2olvlX5OcetOOW5L4CWPx+RmsWQRLEgMqkonKUSiJMe90NXzgNvfqtqTPKB7gS5hCg==
+  checksum: sha256:5de96806106cd5874a691d65f682a797cf59b62bef31e4b16436a95bee2a56f3
+  signature: VVyLcYJ/PHeqXzlyJJEqvfF0FyKvk8bsZQJpmgtwp+VtOCiPfoU7JE77mxPGc0bb3lOAq0esvSV9xbf7522NDg==

packages/specfact-code-review/module-package.yaml

@@ -1,5 +1,5 @@
 name: nold-ai/specfact-code-review
-version: 0.47.44
+version: 0.47.48
 commands:
   - code
 tier: official
@@ -23,5 +23,5 @@ description: Official SpecFact code review bundle package.
 category: codebase
 bundle_group_command: code
 integrity:
-  checksum: sha256:cecd1326fbe7263666fd436c030c86b64218c33798ad8eb0d72f0fa4d5b48dde
-  signature: vf+BeYHAPkQrWhkw0j8PWzFBAwlNXkXRix6mj525QTiOzAP2PlkMHgvPsOLnDhW9/F+YJw7cqUqLHamgUn/xCA==
+  checksum: sha256:666caa2524a6c569dbecc9450ef690035960de5232e6547904edd813bede2745
+  signature: Yn9yF3FxljA4nzTnN8XtWph9v/K6jeg8mAkeBN/yDjx5sCeyKDQ9DWCHJhLtMeNbfW1cQESdAlC+P2KFx1fgCw==

packages/specfact-codebase/module-package.yaml

@@ -1,5 +1,5 @@
 name: nold-ai/specfact-codebase
-version: 0.41.11
+version: 0.41.15
 commands:
   - code
 tier: official
@@ -24,5 +24,5 @@ description: Official SpecFact codebase bundle package.
 category: codebase
 bundle_group_command: code
 integrity:
-  checksum: sha256:21d8bc02de6e01ecc0b7d68c2ba9f736f90f97b128eb925aca721dbd02874c74
-  signature: H1rUcKFH31LleuADUIuLwghMtHwtKWp+4o5cCZbObumSil9c27bIrdH6u8K04AYChea0vHZld4Pr7S2oIDBZBQ==
+  checksum: sha256:7a9b253f8e3049af7fc86d88d5086e448d1fd97a53d89bb66445b8acece307bb
+  signature: wKEdWS0X4RF5Sc0Lo6+9g2opjejhq/qYLVRgB9z12gHR1Yu/5Tk90bdY4yn1OwkAS3UXHBsHnS5PBViNTEBeBQ==

packages/specfact-codebase/src/specfact_codebase/analyze/commands.py

@@ -3,6 +3,10 @@
 
 This module provides commands for analyzing codebases to determine
 contract coverage, code quality metrics, and enhancement opportunities.
+
+Operating guidance: embedded command examples are not the source of truth;
+CLI help is authoritative, so run the relevant --help command and ask the user
+before acting when examples and runtime behavior diverge.
 """
 
 from __future__ import annotations
@@ -55,7 +59,7 @@ def analyze_contracts(
     bundle: str | None = typer.Option(
         None,
         "--bundle",
-        help="Project bundle name (e.g., legacy-api). Default: active plan from 'specfact plan select'",
+        help="Project bundle name (e.g., legacy-api). Default: active project bundle configuration",
     ),
 ) -> None:
     """
@@ -68,7 +72,7 @@ def analyze_contracts(
     - **Target/Input**: --repo, --bundle (required)
 
     **Examples:**
-        specfact analyze contracts --repo . --bundle legacy-api
+        specfact code analyze contracts --repo . --bundle legacy-api
     """
     if is_debug_mode():
         debug_log_operation("command", "analyze contracts", "started", extra={"repo": str(repo), "bundle": bundle})
@@ -88,7 +92,7 @@ def analyze_contracts(
                     extra={"reason": "no_bundle"},
                 )
             console.print("[bold red]✗[/bold red] Bundle name required")
-            console.print("[yellow]→[/yellow] Use --bundle option or run 'specfact plan select' to set active plan")
+            console.print("[yellow]→[/yellow] Use --bundle option or configure an active project bundle")
             raise typer.Exit(1)
         console.print(f"[dim]Using active plan: {bundle}[/dim]")
 

packages/specfact-codebase/src/specfact_codebase/drift/commands.py

@@ -3,6 +3,10 @@
 
 This module provides commands for detecting drift between actual code/tests
 and specifications.
+
+Operating guidance: embedded command examples are not the source of truth;
+CLI help is authoritative, so run the relevant --help command and ask the user
+before acting when examples and runtime behavior diverge.
 """
 
 from __future__ import annotations
@@ -41,7 +45,7 @@
 def detect_drift(
     # Target/Input
     bundle: str | None = typer.Argument(
-        None, help="Project bundle name (e.g., legacy-api). Default: active plan from 'specfact plan select'"
+        None, help="Project bundle name (e.g., legacy-api). Default: active project bundle configuration"
     ),
     repo: Path = typer.Option(
         Path("."),
@@ -79,8 +83,8 @@ def detect_drift(
     - **Output**: --format, --out
 
     **Examples:**
-        specfact drift detect legacy-api --repo .
-        specfact drift detect my-bundle --repo . --format json --out drift-report.json
+        specfact code drift detect legacy-api --repo .
+        specfact code drift detect my-bundle --repo . --format json --out drift-report.json
     """
     if is_debug_mode():
         debug_log_operation(
@@ -101,7 +105,7 @@ def detect_drift(
                     "command", "drift detect", "failed", error="Bundle name required", extra={"reason": "no_bundle"}
                 )
             console.print("[bold red]✗[/bold red] Bundle name required")
-            console.print("[yellow]→[/yellow] Use --bundle option or run 'specfact plan select' to set active plan")
+            console.print("[yellow]→[/yellow] Use --bundle option or configure an active project bundle")
             raise typer.Exit(1)
         console.print(f"[dim]Using active plan: {bundle}[/dim]")
     from specfact_codebase.sync.drift_detector import DriftDetector

packages/specfact-codebase/src/specfact_codebase/import_cmd/commands.py

@@ -1,4 +1,9 @@
-"""Code-owned import command surface for brownfield workflows."""
+"""Code-owned import command surface for brownfield workflows.
+
+Operating guidance: embedded command examples are not the source of truth;
+CLI help is authoritative, so run the relevant --help command and ask the user
+before acting when examples and runtime behavior diverge.
+"""
 
 from __future__ import annotations
 
@@ -78,7 +83,7 @@ def import_codebase(
     ctx: typer.Context,
     bundle: str | None = typer.Argument(
         None,
-        help="Project bundle name (e.g., legacy-api, auth-module). Default: active plan from 'specfact plan select'.",
+        help="Project bundle name (e.g., legacy-api, auth-module). Default: active project bundle configuration.",
     ),
     repo: Path = typer.Option(
         Path("."),

packages/specfact-codebase/src/specfact_codebase/repro/commands.py

@@ -3,6 +3,10 @@
 
 This module provides commands for running comprehensive validation
 including linting, type checking, contract exploration, and tests.
+
+Operating guidance: embedded command examples are not the source of truth;
+CLI help is authoritative, so run the relevant --help command and ask the user
+before acting when examples and runtime behavior diverge.
 """
 
 from __future__ import annotations
@@ -210,10 +214,10 @@ def main(
     Works on external repositories without requiring SpecFact CLI adoption.
 
     Example:
-        specfact repro --verbose --budget 120
-        specfact repro --repo /path/to/external/repo --verbose
-        specfact repro --fix --budget 120
-        specfact repro --sidecar --sidecar-bundle legacy-api --repo /path/to/repo
+        specfact code repro --verbose --budget 120
+        specfact code repro --repo /path/to/external/repo --verbose
+        specfact code repro --fix --budget 120
+        specfact code repro --sidecar --sidecar-bundle legacy-api --repo /path/to/repo
     """
     # If a subcommand was invoked, don't run the main validation
     if ctx.invoked_subcommand is not None:
@@ -467,9 +471,9 @@ def setup(
     - Provides guidance on next steps
 
     Example:
-        specfact repro setup
-        specfact repro setup --repo /path/to/repo
-        specfact repro setup --install-crosshair
+        specfact code repro setup
+        specfact code repro setup --repo /path/to/repo
+        specfact code repro setup --install-crosshair
     """
     console.print("[bold cyan]Setting up CrossHair configuration...[/bold cyan]")
     console.print(f"[dim]Repository: {repo}[/dim]\n")
@@ -559,7 +563,7 @@ def setup(
     # Summary
     console.print("\n[bold green]✓[/bold green] Setup complete!")
     console.print("\n[bold]Next steps:[/bold]")
-    console.print("  1. Run [cyan]specfact repro[/cyan] to execute validation checks")
+    console.print("  1. Run [cyan]specfact code repro[/cyan] to execute validation checks")
     if not crosshair_available:
         console.print("  2. Install crosshair-tool to enable contract exploration:")
         if env_info.manager == "hatch":

packages/specfact-govern/module-package.yaml

@@ -1,5 +1,5 @@
 name: nold-ai/specfact-govern
-version: 0.40.23
+version: 0.40.27
 commands:
   - govern
 tier: official
@@ -19,5 +19,5 @@ description: Official SpecFact governance bundle package.
 category: govern
 bundle_group_command: govern
 integrity:
-  checksum: sha256:b08213f3b3dfe4dee712646272a204b2f28cd57cf6145edd8d851abacd3635c5
-  signature: HY3pzZz8ryiohpLlG0eVcQIda5/Ls6EMAOwDxQZNKbld8Zmg6kZD0pQtMQ86e2i774D963G6lZvaGs/QE3LYBA==
+  checksum: sha256:27d09167e8b2ed23e49cf6034ee8152547a0ee0287863df186edb02f168791d1
+  signature: goXFzfOeVagn5+31uQ/lKk39m0y27NBbJ4uNI1cf9Td+Ofx8L1TsJ9pv3HrFPRZr4jfNqRaksyKSiwQcc2fLAQ==

packages/specfact-govern/src/specfact_govern/enforce/commands.py

@@ -3,6 +3,10 @@
 
 This module provides commands for configuring enforcement modes
 and validation policies.
+
+Operating guidance: embedded command examples are not the source of truth;
+CLI help is authoritative, so run the relevant --help command and ask the user
+before acting when examples and runtime behavior diverge.
 """
 
 from __future__ import annotations
@@ -213,7 +217,7 @@ def enforce_sdd(
     # Target/Input
     bundle: str | None = typer.Argument(
         None,
-        help="Project bundle name (e.g., legacy-api, auth-module). Default: active plan from 'specfact plan select'",
+        help="Project bundle name (e.g., legacy-api, auth-module). Default: active project bundle configuration",
     ),
     sdd: Path | None = typer.Option(
         None,
@@ -278,7 +282,7 @@ def enforce_sdd(
                     "command", "enforce sdd", "failed", error="Bundle name required", extra={"reason": "no_bundle"}
                 )
             console.print("[bold red]✗[/bold red] Bundle name required")
-            console.print("[yellow]→[/yellow] Use --bundle option or run 'specfact plan select' to set active plan")
+            console.print("[yellow]→[/yellow] Pass the bundle name argument or configure an active project bundle")
             raise typer.Exit(1)
         console.print(f"[dim]Using active plan: {bundle}[/dim]")
 
@@ -309,7 +313,7 @@ def enforce_sdd(
                     extra={"reason": "bundle_missing"},
                 )
             console.print(f"[bold red]✗[/bold red] Project bundle not found: {bundle_dir}")
-            console.print(f"[dim]Create one with: specfact plan init {bundle}[/dim]")
+            console.print(f"[dim]Create or configure project bundle '{bundle}' before rerunning.[/dim]")
             raise typer.Exit(1)
 
         # Find SDD manifest path using discovery utility
@@ -328,7 +332,7 @@ def enforce_sdd(
                 )
             console.print("[bold red]✗[/bold red] SDD manifest not found")
             console.print(f"[dim]Searched for: .specfact/projects/{bundle}/sdd.yaml (bundle-specific)[/dim]")
-            console.print(f"[dim]Create one with: specfact plan harden {bundle}[/dim]")
+            console.print(f"[dim]Update the SDD manifest for '{bundle}' before rerunning.[/dim]")
             raise typer.Exit(1)
 
         sdd = discovered_sdd
@@ -378,7 +382,7 @@ def enforce_sdd(
                     severity=DeviationSeverity.HIGH,
                     description=f"SDD bundle hash mismatch: expected {project_hash[:16]}..., got {sdd_manifest.plan_bundle_hash[:16]}...",
                     location=str(sdd),
-                    fix_hint=f"Run 'specfact plan harden {bundle}' to update SDD manifest with current bundle hash",
+                    fix_hint=f"Update SDD manifest for {bundle} with current bundle hash",
                 )
                 report.add_deviation(deviation)
                 console.print("[bold red]✗[/bold red] Hash mismatch detected")
@@ -559,9 +563,7 @@ def enforce_sdd(
                     console.print("   - Features (add/remove/update)")
                     console.print("   - Stories (add/remove/update)")
                     console.print("   - Product, idea, business, or clarifications")
-                    console.print(
-                        f"\n   [bold]Fix:[/bold] Run [cyan]specfact plan harden {bundle}[/cyan] to update the SDD manifest"
-                    )
+                    console.print(f"\n   [bold]Fix:[/bold] Update the SDD manifest for {bundle}")
                     console.print(
                         "   [dim]This updates the SDD with the current bundle hash and regenerates HOW sections[/dim]"
                     )
@@ -576,11 +578,11 @@ def enforce_sdd(
                         f"   - Invariants/feature: {metrics.invariants_per_feature:.2f} (required: {thresholds.invariants_per_feature})"
                     )
                     console.print("\n   [bold]Fix:[/bold] Add more contracts to stories and invariants to features")
-                    console.print("   [dim]Tip: Use 'specfact plan review' to identify areas needing contracts[/dim]")
+                    console.print("   [dim]Tip: review project bundle contract coverage before rerunning[/dim]")
 
                 console.print("\n[bold cyan]Next Steps:[/bold cyan]")
                 if hash_mismatches:
-                    console.print(f"   1. Update SDD: [cyan]specfact plan harden {bundle}[/cyan]")
+                    console.print(f"   1. Update the SDD manifest for {bundle}")
                 if coverage_issues:
                     console.print("   2. Add contracts: Review features and add @icontract decorators")
                     console.print("   3. Re-validate: Run this command again after fixes")

packages/specfact-project/module-package.yaml

@@ -1,5 +1,5 @@
 name: nold-ai/specfact-project
-version: 0.41.23
+version: 0.41.27
 commands:
   - project
   - plan
@@ -27,5 +27,5 @@ core_compatibility: '>=0.40.0,<1.0.0'
 description: Official SpecFact project bundle package.
 bundle_group_command: project
 integrity:
-  checksum: sha256:34cc434009a5e06cc2565584a0713cd418105d7961f7683ecb116eb73086bfab
-  signature: yBgNCMzBT6dNJOVEHajZlJneB/0ice84uaGYNkxUF6avTn+ZMmGVwWbf6HI4QEeXrohxLF/9PI1mafpqHro2Ag==
+  checksum: sha256:46f4a3f8f43ed79a22021c233579708b9cdeac28ffb9235a17137f6dd73e843f
+  signature: 7cweFoJP3xw+w/2llmLBttkCNCx+9FiTfNPuEk81wjABSNKU7Hu3LUAUS9plUkqSWQMr5fz3/tDH1oMMaZS7Aw==

packages/specfact-project/src/specfact_project/import_cmd/commands.py

@@ -4,6 +4,10 @@
 This module provides commands for importing existing codebases (brownfield) and
 external tool projects (e.g., Spec-Kit, OpenSpec, generic-markdown) and converting them to
 SpecFact contract-driven format using the bridge architecture.
+
+Operating guidance: embedded command examples are not the source of truth;
+CLI help is authoritative, so run the relevant --help command and ask the user
+before acting when examples and runtime behavior diverge.
 """
 
 from __future__ import annotations
@@ -1662,23 +1666,23 @@ def _suggest_next_steps(repo: Path, bundle: str, plan_bundle: PlanBundle | None)
 
     if is_first_run:
         console.print("  [yellow]→[/yellow] [bold]Review your plan:[/bold]")
-        console.print(f"     specfact plan review {bundle}")
+        console.print(f"     Review generated project artifacts for {bundle}")
         console.print("     [dim]Review and refine the generated plan bundle[/dim]\n")
 
         console.print("  [yellow]→[/yellow] [bold]Compare with code:[/bold]")
-        console.print(f"     specfact plan compare --bundle {bundle}")
+        console.print(f"     Review deviations for {bundle}")
         console.print("     [dim]Detect deviations between plan and code[/dim]\n")
 
         console.print("  [yellow]→[/yellow] [bold]Validate SDD:[/bold]")
         console.print(f"     specfact govern enforce sdd {bundle}")
         console.print("     [dim]Check for violations and coverage thresholds[/dim]\n")
     else:
         console.print("  [yellow]→[/yellow] [bold]Review changes:[/bold]")
-        console.print(f"     specfact plan review {bundle}")
+        console.print(f"     Review generated project artifacts for {bundle}")
         console.print("     [dim]Review updates to your plan bundle[/dim]\n")
 
         console.print("  [yellow]→[/yellow] [bold]Check deviations:[/bold]")
-        console.print(f"     specfact plan compare --bundle {bundle}")
+        console.print(f"     Review deviations for {bundle}")
         console.print("     [dim]See what changed since last import[/dim]\n")
 
 
@@ -1723,7 +1727,7 @@ def _suggest_constitution_bootstrap(repo: Path) -> None:
             else:
                 console.print()
                 console.print(
-                    "[dim]💡 Tip: Run 'specfact sdd constitution bootstrap --repo .' to generate constitution[/dim]"
+                    "[dim]💡 Tip: Run 'specfact spec sdd constitution bootstrap --repo .' to generate constitution[/dim]"
                 )
 
 
@@ -1958,9 +1962,9 @@ def from_bridge(
     - **Advanced/Configuration**: --adapter
 
     **Examples:**
-        specfact import from-bridge --repo ./my-project --adapter speckit --write
-        specfact import from-bridge --repo ./my-project --write  # Auto-detect adapter
-        specfact import from-bridge --repo ./my-project --dry-run  # Preview changes
+        specfact code import from-bridge --repo ./my-project --adapter speckit --write
+        specfact code import from-bridge --repo ./my-project --write  # Auto-detect adapter
+        specfact code import from-bridge --repo ./my-project --dry-run  # Preview changes
     """
     from specfact_cli.utils.structure import SpecFactStructure
 
@@ -2403,7 +2407,7 @@ def from_code(
     # Target/Input
     bundle: str | None = typer.Argument(
         None,
-        help="Project bundle name (e.g., legacy-api, auth-module). Default: active plan from 'specfact plan select'",
+        help="Project bundle name (e.g., legacy-api, auth-module). Default: active project bundle configuration",
     ),
     repo: Path = typer.Option(
         Path("."),
@@ -2528,7 +2532,7 @@ def from_code(
                     extra={"reason": "no_bundle"},
                 )
             console.print("[bold red]✗[/bold red] Bundle name required")
-            console.print("[yellow]→[/yellow] Use --bundle option or run 'specfact plan select' to set active plan")
+            console.print("[yellow]→[/yellow] Use --bundle option or configure an active project bundle")
             raise typer.Exit(1)
         console.print(f"[dim]Using active plan: {bundle}[/dim]")