specfact-cli 0.30.4__tar.gz → 0.31.1__tar.gz

specfact_cli-0.30.4/LICENSE.md → specfact_cli-0.31.1/LICENSE

@@ -35,8 +35,7 @@
       "Work" shall mean the work of authorship, whether in Source or
       Object form, made available under the License, as indicated by a
       copyright notice that is included in or attached to the work
-      (which shall not include Communications that are clearly marked or
-      otherwise designated in writing by the copyright owner as "Not a Work").
+      (an example is provided in the Appendix below).
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
@@ -57,8 +56,8 @@
       communication on electronic mailing lists, source code control systems,
       and issue tracking systems that are managed by, or on behalf of, the
       Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is clearly marked or otherwise designated
-      in writing by the copyright owner as "Not a Contribution".
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
 
       "Contributor" shall mean Licensor and any individual or Legal Entity
       on behalf of whom a Contribution has been received by Licensor and

{specfact_cli-0.30.4 → specfact_cli-0.31.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.30.4
+Version: 0.31.1
 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
@@ -45,8 +45,7 @@ License:                                  Apache License
               "Work" shall mean the work of authorship, whether in Source or
               Object form, made available under the License, as indicated by a
               copyright notice that is included in or attached to the work
-              (which shall not include Communications that are clearly marked or
-              otherwise designated in writing by the copyright owner as "Not a Work").
+              (an example is provided in the Appendix below).
         
               "Derivative Works" shall mean any work, whether in Source or Object
               form, that is based on (or derived from) the Work and for which the
@@ -67,8 +66,8 @@ License:                                  Apache License
               communication on electronic mailing lists, source code control systems,
               and issue tracking systems that are managed by, or on behalf of, the
               Licensor for the purpose of discussing and improving the Work, but
-              excluding communication that is clearly marked or otherwise designated
-              in writing by the copyright owner as "Not a Contribution".
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
         
               "Contributor" shall mean Licensor and any individual or Legal Entity
               on behalf of whom a Contribution has been received by Licensor and
@@ -210,7 +209,7 @@ License:                                  Apache License
            WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
            See the License for the specific language governing permissions and
            limitations under the License.
-License-File: LICENSE.md
+License-File: LICENSE
 Keywords: agile,backlog,beartype,ceremonies,cli,contract-driven-development,contracts,crosshair,devops,existing-code,icontract,kanban,legacy,modernization,policy-as-code,property-based-testing,safe,scrum,specfact,specs,tdd,validation
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -286,7 +285,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg?color=22c55e)](https://pypi.org/project/specfact-cli/)
 [![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE.md)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Status](https://img.shields.io/badge/status-beta-F59E0B.svg)](https://github.com/nold-ai/specfact-cli)
 
 <div align="center">
@@ -388,6 +387,10 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 - **Ceremony support teams can run**: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe).
 - **Policy + validation**: DoR/DoD/flow checks plus contract enforcement for production-grade stability.
 
+Recommended command entrypoints:
+- `specfact backlog ceremony standup ...`
+- `specfact backlog ceremony refinement ...`
+
 **Try it now**
 
 - **Coders**: [AI IDE Workflow](docs/guides/ai-ide-workflow.md)
@@ -492,6 +495,9 @@ SpecFact complements your stack rather than replacing it.
 - **[Documentation Index](docs/README.md)**
 - **[Command Reference](docs/reference/commands.md)**
 - **[Backlog Refinement](docs/guides/backlog-refinement.md)**
+- **[Backlog Dependency Analysis](docs/guides/backlog-dependency-analysis.md)**
+- **[Backlog Delta Commands](docs/guides/backlog-delta-commands.md)**
+- **[Project DevOps Flow](docs/guides/project-devops-flow.md)**
 - **[Sidecar Validation](docs/guides/sidecar-validation.md)**
 - **[OpenSpec Journey](docs/guides/openspec-journey.md)**
 
@@ -514,7 +520,7 @@ hatch run contract-test-full
 
 **Apache License 2.0** - Open source and enterprise-friendly.
 
-[Full license](LICENSE.md)
+[Full license](LICENSE)
 
 ---
 

{specfact_cli-0.30.4 → specfact_cli-0.31.1}/README.md

@@ -8,7 +8,7 @@
 
 [![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg?color=22c55e)](https://pypi.org/project/specfact-cli/)
 [![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE.md)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Status](https://img.shields.io/badge/status-beta-F59E0B.svg)](https://github.com/nold-ai/specfact-cli)
 
 <div align="center">
@@ -110,6 +110,10 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 - **Ceremony support teams can run**: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe).
 - **Policy + validation**: DoR/DoD/flow checks plus contract enforcement for production-grade stability.
 
+Recommended command entrypoints:
+- `specfact backlog ceremony standup ...`
+- `specfact backlog ceremony refinement ...`
+
 **Try it now**
 
 - **Coders**: [AI IDE Workflow](docs/guides/ai-ide-workflow.md)
@@ -214,6 +218,9 @@ SpecFact complements your stack rather than replacing it.
 - **[Documentation Index](docs/README.md)**
 - **[Command Reference](docs/reference/commands.md)**
 - **[Backlog Refinement](docs/guides/backlog-refinement.md)**
+- **[Backlog Dependency Analysis](docs/guides/backlog-dependency-analysis.md)**
+- **[Backlog Delta Commands](docs/guides/backlog-delta-commands.md)**
+- **[Project DevOps Flow](docs/guides/project-devops-flow.md)**
 - **[Sidecar Validation](docs/guides/sidecar-validation.md)**
 - **[OpenSpec Journey](docs/guides/openspec-journey.md)**
 
@@ -236,7 +243,7 @@ hatch run contract-test-full
 
 **Apache License 2.0** - Open source and enterprise-friendly.
 
-[Full license](LICENSE.md)
+[Full license](LICENSE)
 
 ---
 

{specfact_cli-0.30.4 → specfact_cli-0.31.1}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.30.4"
+version = "0.31.1"
 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"
-license = { file = "LICENSE.md" }  # Apache License 2.0
+license = { file = "LICENSE" }  # Apache License 2.0
 authors = [
     {name = "NOLD AI (Owner: Dominikus Nold)", email = "hello@noldai.com"}
 ]
@@ -385,7 +385,7 @@ include = [
     "/src",
     "/resources",
     "/README.md",
-    "/LICENSE.md",
+    "/LICENSE",
     "/pyproject.toml",
 ]
 # Exclude development files, tests, docs, tools, etc.

{specfact_cli-0.30.4 → specfact_cli-0.31.1}/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.30.4"
+__version__ = "0.31.1"

{specfact_cli-0.30.4 → specfact_cli-0.31.1}/src/specfact_cli/__init__.py

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

{specfact_cli-0.30.4 → specfact_cli-0.31.1}/src/specfact_cli/adapters/ado.py

@@ -32,6 +32,7 @@ from specfact_cli.models.backlog_item import BacklogItem
 from specfact_cli.models.bridge import BridgeConfig
 from specfact_cli.models.capabilities import ToolCapabilities
 from specfact_cli.models.change import ChangeProposal, ChangeTracking
+from specfact_cli.registry.bridge_registry import BRIDGE_PROTOCOL_REGISTRY
 from specfact_cli.runtime import debug_log_operation, debug_print, is_debug_mode
 from specfact_cli.utils.auth_tokens import get_token, set_token
 
@@ -3136,6 +3137,109 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         return filtered_items
 
+    @beartype
+    @require(lambda project_id: isinstance(project_id, str) and len(project_id) > 0, "project_id must be non-empty")
+    @ensure(lambda result: isinstance(result, list), "Must return list")
+    def fetch_all_issues(self, project_id: str, filters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        """Fetch all ADO work items as provider-agnostic dictionaries for graph building."""
+        original_org = self.org
+        original_project = self.project
+        self.org, self.project = self._resolve_graph_project_context(project_id)
+        try:
+            backlog_filters = BacklogFilters(**(filters or {}))
+            return [item.model_dump() for item in self.fetch_backlog_items(backlog_filters)]
+        finally:
+            self.org = original_org
+            self.project = original_project
+
+    @beartype
+    @require(lambda project_id: isinstance(project_id, str) and len(project_id) > 0, "project_id must be non-empty")
+    @ensure(lambda result: isinstance(result, list), "Must return list")
+    def fetch_relationships(self, project_id: str) -> list[dict[str, Any]]:
+        """Fetch ADO relationship edges for graph building."""
+        relationships: list[dict[str, Any]] = []
+        seen: set[tuple[str, str, str]] = set()
+
+        def _add_edge(source_id: str, target_id: str, relation_type: str) -> None:
+            source = source_id.strip()
+            target = target_id.strip()
+            rel = relation_type.strip().lower()
+            if not source or not target or source == target:
+                return
+            key = (source, target, rel)
+            if key in seen:
+                return
+            seen.add(key)
+            relationships.append({"source_id": source, "target_id": target, "type": rel})
+
+        for item in self.fetch_all_issues(project_id):
+            item_id = str(item.get("id") or item.get("key") or "").strip()
+            if not item_id:
+                continue
+
+            provider_fields = item.get("provider_fields")
+            relation_entries: list[Any] = []
+            if isinstance(provider_fields, dict):
+                relations = provider_fields.get("relations")
+                if isinstance(relations, list):
+                    relation_entries.extend(relations)
+            if isinstance(item.get("relations"), list):
+                relation_entries.extend(item["relations"])
+
+            for relation in relation_entries:
+                if not isinstance(relation, dict):
+                    continue
+                rel_name = str(relation.get("rel") or relation.get("relation") or relation.get("type") or "").lower()
+                target_ref = str(relation.get("url") or relation.get("target") or "")
+                target_id = self._extract_work_item_id_from_reference(target_ref)
+                if not target_id:
+                    continue
+
+                if "hierarchy-forward" in rel_name:
+                    _add_edge(item_id, target_id, "parent")
+                elif "hierarchy-reverse" in rel_name:
+                    _add_edge(target_id, item_id, "parent")
+                elif "dependency-forward" in rel_name or "predecessor-forward" in rel_name:
+                    _add_edge(item_id, target_id, "blocks")
+                elif "dependency-reverse" in rel_name or "predecessor-reverse" in rel_name:
+                    _add_edge(target_id, item_id, "blocks")
+                elif "related" in rel_name:
+                    _add_edge(item_id, target_id, "relates")
+
+        return relationships
+
+    @beartype
+    @require(
+        lambda project_id: isinstance(project_id, str) and len(project_id.strip()) > 0, "project_id must be non-empty"
+    )
+    @ensure(lambda result: isinstance(result, tuple) and len(result) == 2, "Must return (org, project) tuple")
+    def _resolve_graph_project_context(self, project_id: str) -> tuple[str, str]:
+        """Resolve org/project context for graph APIs from linked project_id and adapter defaults."""
+        normalized = project_id.strip()
+        if "/" in normalized:
+            org, project = normalized.split("/", 1)
+            resolved_org = org.strip()
+            resolved_project = project.strip()
+            if resolved_org and resolved_project:
+                return resolved_org, resolved_project
+            raise ValueError(f"Invalid ADO project_id format: {project_id!r}. Expected '<org>/<project>'.")
+
+        # Backward compatibility: allow project-only identifiers when adapter org already exists.
+        if self.org:
+            return self.org, normalized
+        raise ValueError(
+            f"ADO project_id '{project_id}' missing organization. Use '<org>/<project>' or configure adapter org."
+        )
+
+    @beartype
+    @ensure(lambda result: isinstance(result, str), "Work item id extraction must return str")
+    def _extract_work_item_id_from_reference(self, reference: str) -> str:
+        """Extract ADO work item id from relation reference URL/string."""
+        if not reference:
+            return ""
+        match = re.search(r"/workitems/(\d+)", reference, flags=re.IGNORECASE)
+        return match.group(1) if match else ""
+
     @beartype
     def supports_add_comment(self) -> bool:
         """Whether this adapter can add comments (requires token, org, project)."""
@@ -3431,3 +3535,6 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             org=self.org,
             project_name=self.project,
         )
+
+
+BRIDGE_PROTOCOL_REGISTRY.register_implementation("backlog_graph", "ado", AdoAdapter)

{specfact_cli-0.30.4 → specfact_cli-0.31.1}/src/specfact_cli/adapters/github.py

@@ -35,6 +35,7 @@ from specfact_cli.models.backlog_item import BacklogItem
 from specfact_cli.models.bridge import BridgeConfig
 from specfact_cli.models.capabilities import ToolCapabilities
 from specfact_cli.models.change import ChangeProposal, ChangeTracking
+from specfact_cli.registry.bridge_registry import BRIDGE_PROTOCOL_REGISTRY
 from specfact_cli.runtime import debug_log_operation, is_debug_mode
 from specfact_cli.utils.auth_tokens import get_token
 
@@ -2638,6 +2639,157 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
 
         return filtered_items
 
+    @beartype
+    @require(lambda project_id: isinstance(project_id, str) and len(project_id) > 0, "project_id must be non-empty")
+    @ensure(lambda result: isinstance(result, list), "Must return list")
+    def fetch_all_issues(self, project_id: str, filters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        """Fetch all backlog items as provider-agnostic dictionaries for graph building."""
+        owner, repo = project_id.split("/", 1) if "/" in project_id else (self.repo_owner, self.repo_name)
+        previous_owner = self.repo_owner
+        previous_repo = self.repo_name
+        try:
+            if owner and repo:
+                self.repo_owner = owner
+                self.repo_name = repo
+            backlog_filters = BacklogFilters(**(filters or {}))
+            enriched_items: list[dict[str, Any]] = []
+            for item in self.fetch_backlog_items(backlog_filters):
+                issue_dict = item.model_dump()
+                inferred_type = self._infer_graph_item_type(issue_dict)
+                if inferred_type:
+                    issue_dict["type"] = inferred_type
+                enriched_items.append(issue_dict)
+            return enriched_items
+        finally:
+            self.repo_owner = previous_owner
+            self.repo_name = previous_repo
+
+    @beartype
+    @require(lambda project_id: isinstance(project_id, str) and len(project_id) > 0, "project_id must be non-empty")
+    @ensure(lambda result: isinstance(result, list), "Must return list")
+    def fetch_relationships(self, project_id: str) -> list[dict[str, Any]]:
+        """Fetch relationships for a GitHub backlog project."""
+        relationships: list[dict[str, Any]] = []
+        seen: set[tuple[str, str, str]] = set()
+
+        def _add_edge(source_id: str, target_id: str, relation_type: str) -> None:
+            source = source_id.strip()
+            target = target_id.strip()
+            rel = relation_type.strip().lower()
+            if not source or not target or source == target:
+                return
+            key = (source, target, rel)
+            if key in seen:
+                return
+            seen.add(key)
+            relationships.append({"source_id": source, "target_id": target, "type": rel})
+
+        issues = self.fetch_all_issues(project_id)
+        for issue in issues:
+            issue_id = str(issue.get("id") or issue.get("key") or "").strip()
+            if not issue_id:
+                continue
+
+            provider_fields = issue.get("provider_fields")
+            if isinstance(provider_fields, dict):
+                linked_issues = provider_fields.get("linked_issues", [])
+                if isinstance(linked_issues, list):
+                    for linked in linked_issues:
+                        if not isinstance(linked, dict):
+                            continue
+                        relation = str(linked.get("relation") or linked.get("type") or "").strip().lower()
+                        linked_id = str(linked.get("id") or linked.get("number") or "").strip()
+                        if not linked_id:
+                            linked_url = str(linked.get("url") or "")
+                            linked_match = re.search(r"/issues/(\d+)", linked_url, flags=re.IGNORECASE)
+                            linked_id = linked_match.group(1) if linked_match else ""
+                        if not linked_id:
+                            continue
+                        if relation in {"blocks", "block"}:
+                            _add_edge(issue_id, linked_id, "blocks")
+                        elif relation in {"blocked_by", "blocked by"}:
+                            _add_edge(linked_id, issue_id, "blocks")
+                        elif relation in {"parent", "parent_of"}:
+                            _add_edge(linked_id, issue_id, "parent")
+                        elif relation in {"child", "child_of"}:
+                            _add_edge(issue_id, linked_id, "parent")
+                        else:
+                            _add_edge(issue_id, linked_id, "relates")
+
+            body = str(issue.get("body_markdown") or issue.get("description") or "")
+            for match in re.finditer(r"(?im)\bblocks?\s+#(\d+)\b", body):
+                _add_edge(issue_id, match.group(1), "blocks")
+            for match in re.finditer(r"(?im)\bblocked\s+by\s+#(\d+)\b", body):
+                _add_edge(match.group(1), issue_id, "blocks")
+            for match in re.finditer(r"(?im)\bdepends\s+on\s+#(\d+)\b", body):
+                _add_edge(match.group(1), issue_id, "blocks")
+            for match in re.finditer(r"(?im)\bparent\s*[:#]?\s*#(\d+)\b", body):
+                _add_edge(match.group(1), issue_id, "parent")
+            for match in re.finditer(r"(?im)\bchild(?:ren)?\s*[:#]?\s*#(\d+)\b", body):
+                _add_edge(issue_id, match.group(1), "parent")
+            for match in re.finditer(r"(?im)\b(?:related\s+to|relates?\s+to|refs?|references?)\s+#(\d+)\b", body):
+                _add_edge(issue_id, match.group(1), "relates")
+
+        return relationships
+
+    @beartype
+    @ensure(lambda result: result is None or isinstance(result, str), "Type inference must return str or None")
+    def _infer_graph_item_type(self, issue_payload: dict[str, Any]) -> str | None:
+        """Infer normalized graph item type from GitHub issue payload."""
+        alias_map = {
+            "epic": "epic",
+            "feature": "feature",
+            "story": "story",
+            "user story": "story",
+            "task": "task",
+            "bug": "bug",
+            "sub-task": "sub_task",
+            "sub task": "sub_task",
+            "subtask": "sub_task",
+        }
+
+        def _normalize(raw_value: str) -> str | None:
+            normalized = raw_value.strip().lower().replace("_", " ").replace("-", " ")
+            if not normalized:
+                return None
+            if normalized in alias_map:
+                return alias_map[normalized]
+            for separator in (":", "/"):
+                if separator in normalized:
+                    suffix = normalized.split(separator)[-1].strip()
+                    if suffix in alias_map:
+                        return alias_map[suffix]
+            for token, mapped in alias_map.items():
+                if normalized.startswith(f"{token} ") or normalized.endswith(f" {token}"):
+                    return mapped
+            return None
+
+        for key in ("type", "work_item_type"):
+            value = issue_payload.get(key)
+            if isinstance(value, str):
+                mapped = _normalize(value)
+                if mapped:
+                    return mapped
+
+        tags = issue_payload.get("tags")
+        if isinstance(tags, list):
+            for tag in tags:
+                if isinstance(tag, str):
+                    mapped = _normalize(tag)
+                    if mapped:
+                        return mapped
+
+        title = issue_payload.get("title")
+        if isinstance(title, str):
+            mapped = _normalize(title)
+            if mapped:
+                return mapped
+            for token, mapped_value in alias_map.items():
+                if title.lower().startswith(f"[{token}]"):
+                    return mapped_value
+
+        return None
+
     @beartype
     def supports_add_comment(self) -> bool:
         """Whether this adapter can add comments (requires token and repo)."""
@@ -2818,3 +2970,6 @@ class GitHubAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         from specfact_cli.backlog.converter import convert_github_issue_to_backlog_item
 
         return convert_github_issue_to_backlog_item(updated_issue, provider="github")
+
+
+BRIDGE_PROTOCOL_REGISTRY.register_implementation("backlog_graph", "github", GitHubAdapter)

{specfact_cli-0.30.4 → specfact_cli-0.31.1}/src/specfact_cli/backlog/mappers/github_mapper.py

@@ -246,11 +246,25 @@ class GitHubFieldMapper(FieldMapper):
         Returns:
             Work item type or None if not found
         """
-        # Common work item type labels
-        work_item_types = ["Epic", "Feature", "User Story", "Story", "Task", "Bug", "Bugfix"]
+        # Common work item type labels (case-insensitive + prefixed forms)
+        normalized_to_canonical = {
+            "epic": "Epic",
+            "feature": "Feature",
+            "user story": "User Story",
+            "story": "Story",
+            "task": "Task",
+            "bug": "Bug",
+            "bugfix": "Bugfix",
+        }
         for label in label_names:
-            if label in work_item_types:
-                return label
+            normalized = str(label).strip().lower()
+            if normalized in normalized_to_canonical:
+                return normalized_to_canonical[normalized]
+            if normalized.startswith(("type:", "kind:", "work-item:")):
+                _, _, suffix = normalized.partition(":")
+                canonical = normalized_to_canonical.get(suffix.strip())
+                if canonical:
+                    return canonical
 
         # Check issue type metadata if available
         issue_type = item_data.get("issue_type") or item_data.get("type")

{specfact_cli-0.30.4 → specfact_cli-0.31.1}/src/specfact_cli/cli.py

@@ -59,6 +59,7 @@ from specfact_cli.modes import OperationalMode, detect_mode
 # Command groups are registered via CommandRegistry (bootstrap); no top-level command imports.
 from specfact_cli.registry import CommandRegistry
 from specfact_cli.registry.bootstrap import register_builtin_commands
+from specfact_cli.registry.metadata import CommandMetadata
 from specfact_cli.runtime import get_configured_console, init_debug_log_file, set_debug_mode
 from specfact_cli.utils.progressive_disclosure import ProgressiveDisclosureGroup
 from specfact_cli.utils.structured_io import StructuredFormat
@@ -521,7 +522,36 @@ def _patch_typer_build() -> None:
 
 register_builtin_commands()
 _patch_typer_build()
-for _name, _meta in CommandRegistry.list_commands_for_help():
+
+
+def _grouped_command_order(
+    commands: list[tuple[str, CommandMetadata]],
+) -> list[tuple[str, CommandMetadata]]:
+    """Keep registration order while grouping extension commands after their base group."""
+    names = {name for name, _meta in commands}
+    base_commands: list[tuple[str, CommandMetadata]] = []
+    extension_by_base: dict[str, list[tuple[str, CommandMetadata]]] = {}
+    orphan_extensions: list[tuple[str, CommandMetadata]] = []
+
+    for name, meta in commands:
+        if "-" not in name:
+            base_commands.append((name, meta))
+            continue
+        base_name = name.split("-", 1)[0]
+        if base_name in names:
+            extension_by_base.setdefault(base_name, []).append((name, meta))
+        else:
+            orphan_extensions.append((name, meta))
+
+    ordered: list[tuple[str, CommandMetadata]] = []
+    for name, meta in base_commands:
+        ordered.append((name, meta))
+        ordered.extend(extension_by_base.get(name, []))
+    ordered.extend(orphan_extensions)
+    return ordered
+
+
+for _name, _meta in _grouped_command_order(CommandRegistry.list_commands_for_help()):
     app.add_typer(_make_lazy_typer(_name, _meta.help), name=_name, help=_meta.help)
 
 

{specfact_cli-0.30.4 → specfact_cli-0.31.1}/src/specfact_cli/models/project.py

@@ -85,6 +85,28 @@ class ProjectMetadata(BaseModel):
     stability: str = Field("alpha", description="Stability level: alpha | beta | stable")
     breaking_changes: list[dict[str, str]] = Field(default_factory=list, description="Breaking change history")
     version_history: list[dict[str, str]] = Field(default_factory=list, description="Version change log")
+    extensions: dict[str, Any] = Field(default_factory=dict, description="Module-scoped metadata extensions")
+
+    @beartype
+    @require(lambda namespace: namespace.strip() != "", "Extension namespace must be non-empty")
+    @require(lambda key: key.strip() != "", "Extension key must be non-empty")
+    def set_extension(self, namespace: str, key: str, value: Any) -> None:
+        """Set a module-scoped extension value."""
+        namespace_data = self.extensions.get(namespace)
+        if not isinstance(namespace_data, dict):
+            namespace_data = {}
+            self.extensions[namespace] = namespace_data
+        namespace_data[key] = value
+
+    @beartype
+    @require(lambda namespace: namespace.strip() != "", "Extension namespace must be non-empty")
+    @require(lambda key: key.strip() != "", "Extension key must be non-empty")
+    def get_extension(self, namespace: str, key: str, default: Any = None) -> Any:
+        """Get a module-scoped extension value."""
+        namespace_data = self.extensions.get(namespace)
+        if not isinstance(namespace_data, dict):
+            return default
+        return namespace_data.get(key, default)
 
 
 class BundleChecksums(BaseModel):