specfact-cli 0.27.0__tar.gz → 0.28.0__tar.gz

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/.gitignore

@@ -107,6 +107,10 @@ docs/internal/
 .github/prompts/specfact.*.md
 .github/prompts/opsx-*.md
 
+.claude/commands/opsx/
+.claude/skills/openspec-*/
+!.claude/skills/openspec-workflows/
+
 # Semgrep rules (generated from tools/semgrep/ - source rules are versioned)
 .semgrep/
 

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.27.0
+Version: 0.28.0
 Summary: The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git
@@ -414,6 +414,19 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 
 ---
 
+## Developer Note: Command Layout
+
+- Primary command implementations live in `src/specfact_cli/modules/<module>/src/commands.py`.
+- Legacy imports from `src/specfact_cli/commands/*.py` are compatibility shims and only guarantee `app` re-exports.
+- Preferred imports for module code:
+  - `from specfact_cli.modules.<module>.src.commands import app`
+  - `from specfact_cli.modules.<module>.src.commands import <symbol>`
+- Shim deprecation timeline:
+  - Legacy shim usage is deprecated for non-`app` symbols now.
+  - Shim removal is planned no earlier than `v0.30` (or the next major migration window).
+
+---
+
 ## Where SpecFact Fits
 
 SpecFact complements your stack rather than replacing it.

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/README.md

@@ -136,6 +136,19 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 
 ---
 
+## Developer Note: Command Layout
+
+- Primary command implementations live in `src/specfact_cli/modules/<module>/src/commands.py`.
+- Legacy imports from `src/specfact_cli/commands/*.py` are compatibility shims and only guarantee `app` re-exports.
+- Preferred imports for module code:
+  - `from specfact_cli.modules.<module>.src.commands import app`
+  - `from specfact_cli.modules.<module>.src.commands import <symbol>`
+- Shim deprecation timeline:
+  - Legacy shim usage is deprecated for non-`app` symbols now.
+  - Shim removal is planned no earlier than `v0.30` (or the next major migration window).
+
+---
+
 ## Where SpecFact Fits
 
 SpecFact complements your stack rather than replacing it.

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.27.0"
+version = "0.28.0"
 description = "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -193,8 +193,8 @@ validate-prompts = "python tools/validate_prompts.py"
 # Development scripts
 test = "pytest {args}"
 test-cov = "pytest --cov=src --cov-report=term-missing {args}"
-type-check = "basedpyright {args}"
-lint = "ruff format . --check && basedpyright && ruff check . && pylint src tests tools"
+type-check = "basedpyright --pythonpath $(python -c 'import sys; print(sys.executable)') {args}"
+lint = "ruff format . --check && basedpyright --pythonpath $(python -c 'import sys; print(sys.executable)') && ruff check . && pylint src tests tools"
 governance = "pylint src tests tools --reports=y --output-format=parseable"
 format = "ruff check . --fix && ruff format ."
 
@@ -705,6 +705,9 @@ ignore = [
 "src/specfact_cli/commands/**/*" = [
     "B008",   # typer.Option/Argument in defaults (common Typer pattern)
 ]
+"src/specfact_cli/modules/**/src/commands.py" = [
+    "B008",   # typer.Option/Argument in defaults (common Typer pattern)
+]
 
 [tool.ruff.lint.isort]
 # Match isort ruff profile configuration

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.27.0"
+__version__ = "0.28.0"

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/src/specfact_cli/__init__.py

@@ -8,6 +8,6 @@ This package provides command-line tools for:
 - Supporting agile ceremonies and team workflows
 """
 
-__version__ = "0.27.0"
+__version__ = "0.28.0"
 
 __all__ = ["__version__"]

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/src/specfact_cli/analyzers/graph_analyzer.py

@@ -370,11 +370,11 @@ class GraphAnalyzer:
 
         Tries multiple strategies:
         1. Exact match
-        2. Last part match (e.g., "import_cmd" matches "src.specfact_cli.commands.import_cmd")
-        3. Partial path match (e.g., "specfact_cli.commands" matches "src.specfact_cli.commands.import_cmd")
+        2. Last part match (e.g., "import_cmd" matches "src.specfact_cli.modules.import_cmd.src.commands")
+        3. Partial path match (e.g., "specfact_cli.commands" matches "src.specfact_cli.modules.import_cmd.src.commands")
 
         Args:
-            imported: Imported module name (e.g., "specfact_cli.commands.import_cmd")
+            imported: Imported module name (e.g., "specfact_cli.modules.import_cmd.src.commands")
             known_modules: List of known module names in the graph
 
         Returns:
@@ -385,14 +385,14 @@ class GraphAnalyzer:
             return imported
 
         # Strategy 2: Last part match
-        # e.g., "import_cmd" matches "src.specfact_cli.commands.import_cmd"
+        # e.g., "import_cmd" matches "src.specfact_cli.modules.import_cmd.src.commands"
         imported_last = imported.split(".")[-1]
         for module in known_modules:
             if module.endswith(f".{imported_last}") or module == imported_last:
                 return module
 
         # Strategy 3: Partial path match
-        # e.g., "specfact_cli.commands" matches "src.specfact_cli.commands.import_cmd"
+        # e.g., "specfact_cli.commands" matches "src.specfact_cli.modules.import_cmd.src.commands"
         for module in known_modules:
             # Check if imported is a prefix of module
             if module.startswith(imported + ".") or module == imported:
@@ -406,7 +406,7 @@ class GraphAnalyzer:
         for module in known_modules:
             module_parts = module.split(".")
             # Check if there's overlap in the path
-            # e.g., "commands.import_cmd" might match "src.specfact_cli.commands.import_cmd"
+            # e.g., "commands.import_cmd" might match "src.specfact_cli.modules.import_cmd.src.commands"
             if len(imported_parts) >= 2 and len(module_parts) >= 2 and imported_parts[-2:] == module_parts[-2:]:
                 return module
 

specfact_cli-0.28.0/src/specfact_cli/commands/analyze.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/analyze/."""
+
+from specfact_cli.modules.analyze.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/auth.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/auth/."""
+
+from specfact_cli.modules.auth.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/backlog_commands.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/backlog/."""
+
+from specfact_cli.modules.backlog.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/contract_cmd.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/contract/."""
+
+from specfact_cli.modules.contract.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/drift.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/drift/."""
+
+from specfact_cli.modules.drift.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/enforce.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/enforce/."""
+
+from specfact_cli.modules.enforce.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/generate.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/generate/."""
+
+from specfact_cli.modules.generate.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/import_cmd.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/import_cmd/."""
+
+from specfact_cli.modules.import_cmd.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/init.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/init/."""
+
+from specfact_cli.modules.init.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/migrate.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/migrate/."""
+
+from specfact_cli.modules.migrate.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/plan.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/plan/."""
+
+from specfact_cli.modules.plan.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/project_cmd.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/project/."""
+
+from specfact_cli.modules.project.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/repro.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/repro/."""
+
+from specfact_cli.modules.repro.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/sdd.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/sdd/."""
+
+from specfact_cli.modules.sdd.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/spec.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/spec/."""
+
+from specfact_cli.modules.spec.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/sync.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/sync/."""
+
+from specfact_cli.modules.sync.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/update.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/upgrade/."""
+
+from specfact_cli.modules.upgrade.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/commands/validate.py

@@ -0,0 +1,6 @@
+"""Backward-compatible app shim. Implementation moved to modules/validate/."""
+
+from specfact_cli.modules.validate.src.commands import app
+
+
+__all__ = ["app"]

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/src/specfact_cli/generators/persona_exporter.py

@@ -108,7 +108,7 @@ class PersonaExporter:
         Returns:
             Template context dictionary
         """
-        from specfact_cli.commands.project_cmd import match_section_pattern
+        from specfact_cli.utils.persona_ownership import match_section_pattern
 
         context: dict[str, Any] = {
             "bundle_name": bundle.bundle_name,

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/src/specfact_cli/merge/resolver.py

@@ -355,7 +355,7 @@ class PersonaMergeResolver:
         Returns:
             Persona name if persona owns section, None otherwise
         """
-        from specfact_cli.commands.project_cmd import check_persona_ownership
+        from specfact_cli.utils.persona_ownership import check_persona_ownership
 
         if check_persona_ownership(persona, manifest, section_path):
             return persona

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/src/specfact_cli/models/plan.py

@@ -290,4 +290,7 @@ class PlanBundle(BaseModel):
                 external_dependencies=[],
                 summary=None,
             )
-        self.metadata.summary = self.compute_summary(include_hash=include_hash)
+        metadata = self.metadata
+        if metadata is None:
+            return
+        metadata.summary = self.compute_summary(include_hash=include_hash)

specfact_cli-0.28.0/src/specfact_cli/modules/analyze/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/analyze/src/app.py

@@ -0,0 +1,6 @@
+"""analyze command entrypoint."""
+
+from specfact_cli.modules.analyze.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/modules/auth/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/auth/src/app.py

@@ -0,0 +1,6 @@
+"""auth command entrypoint."""
+
+from specfact_cli.modules.auth.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/modules/backlog/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/backlog/src/app.py

@@ -0,0 +1,6 @@
+"""backlog command entrypoint."""
+
+from specfact_cli.modules.backlog.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.27.0/src/specfact_cli/commands/backlog_commands.py → specfact_cli-0.28.0/src/specfact_cli/modules/backlog/src/commands.py

@@ -1538,14 +1538,16 @@ def refine(
                 built_in_loaded = True
             else:
                 # Fallback: Try relative to repo root (development mode)
-                repo_root = Path(__file__).parent.parent.parent.parent
+                # __file__ = src/specfact_cli/modules/backlog/src/commands.py → 6 parents to repo root
+                repo_root = Path(__file__).parent.parent.parent.parent.parent.parent
                 resources_templates_dir = repo_root / "resources" / "templates" / "backlog"
                 if resources_templates_dir.exists():
                     registry.load_templates_from_directory(resources_templates_dir)
                     built_in_loaded = True
                 else:
                     # 2. Fallback to src/specfact_cli/templates/ for backward compatibility
-                    src_templates_dir = Path(__file__).parent.parent / "templates"
+                    # __file__ → 4 parents to reach src/specfact_cli/
+                    src_templates_dir = Path(__file__).parent.parent.parent.parent / "templates"
                     if src_templates_dir.exists():
                         registry.load_templates_from_directory(src_templates_dir)
                         built_in_loaded = True

specfact_cli-0.28.0/src/specfact_cli/modules/contract/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/contract/src/app.py

@@ -0,0 +1,6 @@
+"""contract command entrypoint."""
+
+from specfact_cli.modules.contract.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.27.0/src/specfact_cli/commands/contract_cmd.py → specfact_cli-0.28.0/src/specfact_cli/modules/contract/src/commands.py

@@ -113,7 +113,7 @@ def init_contract(
             if not bundle_names:
                 print_error("No valid bundle names found")
                 raise typer.Exit(1)
-                bundle = Prompt.ask("Select bundle", choices=bundle_names)
+            bundle = Prompt.ask("Select bundle", choices=bundle_names)
         elif bundle is None:
             print_error("Bundle not specified and no active bundle found")
             raise typer.Exit(1)
@@ -278,7 +278,7 @@ def _update_contract_index(bundle: ProjectBundle, feature_key: str, contract_pat
             endpoints_count = count_endpoints(contract_data)
             checksum = hashlib.sha256(contract_file.read_bytes()).hexdigest()
         except Exception:
-            pass
+            print_warning(f"Failed to load or analyze contract file '{contract_file}'. Using default metadata.")
 
     contract_index = ContractIndex(
         feature_key=feature_key,
@@ -718,7 +718,10 @@ def serve_contract(
 
                 feature_choices = [f"{key}: {obj.title}" for key, obj in features_with_contracts]
                 selected = Prompt.ask("Select feature contract", choices=feature_choices)
-                feature = selected.split(":")[0]
+                feature = selected.split(":", 1)[0].strip()
+                if feature not in bundle_obj.features:
+                    print_error(f"Selected feature '{feature}' not found in bundle")
+                    raise typer.Exit(1)
                 feature_obj = bundle_obj.features[feature]
                 if not feature_obj.contract:
                     print_error(f"Feature '{feature}' has no contract")

specfact_cli-0.28.0/src/specfact_cli/modules/drift/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/drift/src/app.py

@@ -0,0 +1,6 @@
+"""drift command entrypoint."""
+
+from specfact_cli.modules.drift.src.commands import app
+
+
+__all__ = ["app"]

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/src/specfact_cli/modules/enforce/module-package.yaml

@@ -6,5 +6,6 @@ commands:
 command_help:
   enforce: "Configure quality gates"
 pip_dependencies: []
-module_dependencies: []
+module_dependencies:
+  - plan
 tier: community

specfact_cli-0.28.0/src/specfact_cli/modules/enforce/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/enforce/src/app.py

@@ -0,0 +1,6 @@
+"""enforce command entrypoint."""
+
+from specfact_cli.modules.enforce.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.27.0/src/specfact_cli/commands/enforce.py → specfact_cli-0.28.0/src/specfact_cli/modules/enforce/src/commands.py

@@ -296,7 +296,7 @@ def enforce_sdd(
                 raise typer.Exit(1)
 
             # Convert to PlanBundle for compatibility with validation functions
-            from specfact_cli.commands.plan import _convert_project_bundle_to_plan_bundle
+            from specfact_cli.modules.plan.src.commands import _convert_project_bundle_to_plan_bundle
 
             plan_bundle = _convert_project_bundle_to_plan_bundle(project_bundle)
 

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/src/specfact_cli/modules/generate/module-package.yaml

@@ -6,5 +6,6 @@ commands:
 command_help:
   generate: "Generate artifacts from SDD and plans"
 pip_dependencies: []
-module_dependencies: []
+module_dependencies:
+  - plan
 tier: community

specfact_cli-0.28.0/src/specfact_cli/modules/generate/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/generate/src/app.py

@@ -0,0 +1,6 @@
+"""generate command entrypoint."""
+
+from specfact_cli.modules.generate.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.27.0/src/specfact_cli/commands/generate.py → specfact_cli-0.28.0/src/specfact_cli/modules/generate/src/commands.py

@@ -241,7 +241,7 @@ def generate_contracts(
             plan_hash = None
             if format_type == BundleFormat.MODULAR or bundle:
                 # Load modular ProjectBundle and convert to PlanBundle for compatibility
-                from specfact_cli.commands.plan import _convert_project_bundle_to_plan_bundle
+                from specfact_cli.modules.plan.src.commands import _convert_project_bundle_to_plan_bundle
 
                 project_bundle = load_bundle_with_progress(plan_path, validate_hashes=False, console_instance=console)
 

specfact_cli-0.28.0/src/specfact_cli/modules/import_cmd/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/import_cmd/src/app.py

@@ -0,0 +1,6 @@
+"""import_cmd command entrypoint."""
+
+from specfact_cli.modules.import_cmd.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/modules/init/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/init/src/app.py

@@ -0,0 +1,6 @@
+"""init command entrypoint."""
+
+from specfact_cli.modules.init.src.commands import app
+
+
+__all__ = ["app"]

specfact_cli-0.28.0/src/specfact_cli/modules/migrate/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/migrate/src/app.py

@@ -0,0 +1,6 @@
+"""migrate command entrypoint."""
+
+from specfact_cli.modules.migrate.src.commands import app
+
+
+__all__ = ["app"]

{specfact_cli-0.27.0 → specfact_cli-0.28.0}/src/specfact_cli/modules/plan/module-package.yaml

@@ -6,5 +6,6 @@ commands:
 command_help:
   plan: "Manage development plans"
 pip_dependencies: []
-module_dependencies: []
+module_dependencies:
+  - sync
 tier: community

specfact_cli-0.28.0/src/specfact_cli/modules/plan/src/__init__.py

@@ -0,0 +1 @@
+"""Module package source namespace."""

specfact_cli-0.28.0/src/specfact_cli/modules/plan/src/app.py

@@ -0,0 +1,6 @@
+"""plan command entrypoint."""
+
+from specfact_cli.modules.plan.src.commands import app
+
+
+__all__ = ["app"]