specfact-cli 0.43.2__tar.gz → 0.43.3__tar.gz

{specfact_cli-0.43.2 → specfact_cli-0.43.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.43.2
+Version: 0.43.3
 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
@@ -281,9 +281,10 @@ Description-Content-Type: text/markdown
 
 # SpecFact CLI
 
-> **The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow.**
-> Keep backlog, specs, tests, and code in sync so changes made by people or AI copilots do not break production.
-> Works for brand-new projects and long-lived codebases - even if you are new to coding.
+> **SpecFact is the validation and alignment layer for software delivery.**
+> It adds the missing validation layer that keeps backlog intent, specifications, tests, and code
+> from drifting apart across AI-assisted coding, brownfield systems, and governed delivery.
+> Use it to move fast without losing rigor.
 
 **No API keys required. Works offline. Zero vendor lock-in.**
 
@@ -304,21 +305,54 @@ invoke SpecFact as part of a command chain.
 
 ---
 
-## Documentation Topology
+## What is SpecFact?
 
-`docs.specfact.io` is the canonical docs entry point for SpecFact.
+SpecFact is the validation and alignment layer for software delivery.
 
-- Core CLI/runtime/platform documentation remains owned by `specfact-cli`.
-- Module-specific deep docs are canonically owned by `specfact-cli-modules`.
-- The live modules docs site is currently published at `https://modules.specfact.io/`.
+It is a local CLI that helps you keep the intent behind a change aligned from
+backlog or idea through specifications, implementation, and checks. The “Swiss-knife CLI” metaphor
+fits because SpecFact gives you a set of focused tools for specific delivery problems, not a vague
+bag of features.
 
-Use this repository's docs for the overall SpecFact workflow, CLI runtime lifecycle, module registry, trust model, and command-group topology.
-Use the modules docs site for bundle-specific deep dives, adapter details, workflow tutorials, and module-authoring guidance.
-In short, module-specific deep docs are canonically owned by `specfact-cli-modules`.
+In practice, SpecFact helps you:
+- add guardrails to AI-assisted and fast-moving greenfield work
+- reverse-engineer large brownfield codebases into trustworthy structured understanding
+- reduce the “I wanted X but got Y” drift between backlog, spec, and implementation
+- move from local rigor toward team and enterprise policy enforcement
 
----
+## Why does it exist?
+
+Modern delivery drifts in predictable ways:
+- AI-generated quick wins often lack the validation layer needed for mid- and long-term reliability
+- brownfield systems often have missing or drifted specs, so teams need to reverse-engineer reality
+- backlog intent gets reinterpreted into something else before it reaches code
+- teams working with different skill levels, opinions, and AI IDE setups need consistent review and
+  policy enforcement
+
+SpecFact exists to reduce that drift. It helps teams understand what is really there, express what
+should happen more accurately, and validate that the result still matches the original intent.
+
+## Why should I use it?
+
+Use SpecFact if you want one of these outcomes:
+- ship AI-assisted changes faster without accepting fragile “looks fine to me” quality
+- understand a legacy or unfamiliar codebase before changing it
+- hand brownfield insight into OpenSpec, Spec-Kit, or other spec-first workflows
+- keep backlog expectations, specifications, and implementation from silently diverging
+- enforce shared rules consistently across developers and CI/CD
 
-## Start Here (60 seconds)
+## What do I get?
+
+With SpecFact, you get:
+- a deterministic local CLI instead of another opaque SaaS dependency
+- a validation layer around fast-moving implementation work
+- codebase analysis and sidecar flows for brownfield understanding
+- stronger backlog/spec/code alignment for real delivery workflows
+- a path from individual rigor to organization-level policy enforcement
+
+## How do I get started?
+
+### Start Here (5 minutes)
 
 ### Install
 
@@ -330,38 +364,104 @@ uvx specfact-cli@latest
 pip install -U specfact-cli
 ```
 
-### Bootstrap and IDE Setup
+### Bootstrap
 
 ```bash
-# First run: install official bundles
+# Recommended first run
 specfact init --profile solo-developer
-
-# Alternative bundle selection
-specfact init --install backlog,codebase
-specfact init --install all
-
-# IDE prompt/template setup
-specfact init ide
-specfact init ide --ide cursor
-specfact init ide --ide vscode
 ```
 
-`specfact init ide` discovers prompt resources from installed workflow modules and exports them to your IDE. If module prompt payloads are not installed yet, the CLI uses packaged fallback resources.
-
-### Run Your First Flow
+### Get First Value
 
 ```bash
-# Analyze an existing codebase
+# Analyze a codebase you care about
 specfact code import my-project --repo .
 
-# Snapshot current project state
+# Snapshot the project state for follow-up workflows
 specfact project snapshot --bundle my-project
 
-# Validate external code without modifying source
+# Validate external code without modifying the target repo
 specfact code validate sidecar init my-project /path/to/repo
 specfact code validate sidecar run my-project /path/to/repo
 ```
 
+That path gives you a concrete first win: SpecFact understands your project context and gives you a
+validated starting point instead of jumping straight into blind change work.
+
+### AI IDE Setup
+
+```bash
+specfact init ide
+specfact init ide --ide cursor
+specfact init ide --ide vscode
+```
+
+`specfact init ide` discovers prompt resources from installed workflow modules and exports them to
+your IDE. If module prompt payloads are not installed yet, the CLI uses packaged fallback resources.
+
+## Choose Your Path
+
+### Greenfield and AI-assisted delivery
+
+Use SpecFact as the validation layer around fast-moving implementation work.
+
+Start with:
+- `specfact init --profile solo-developer`
+- `specfact code validate sidecar init <bundle> /path/to/repo`
+- `specfact code validate sidecar run <bundle> /path/to/repo`
+
+### Brownfield and reverse engineering
+
+Use SpecFact to understand an existing system before you change it, then hand that understanding
+into spec-first tools such as OpenSpec or Spec-Kit.
+
+Start with:
+- `specfact code import my-project --repo .`
+- `specfact project snapshot --bundle my-project`
+- `specfact code validate sidecar init my-project /path/to/repo`
+- `specfact code validate sidecar run my-project /path/to/repo`
+
+### Backlog to code alignment
+
+Use SpecFact when the problem is not only code quality, but drift between expectations and delivery.
+Backlog commands require a backlog-enabled profile or installed backlog bundle before the workflow
+commands are available.
+
+Start with:
+- `specfact init --profile backlog-team`
+- `specfact backlog ceremony standup ...`
+- `specfact backlog ceremony refinement ...`
+- `specfact backlog verify-readiness --bundle <bundle-name>`
+
+### Team and policy enforcement
+
+Use SpecFact when multiple developers and AI IDEs need consistent checks and review behavior.
+
+Start with:
+- `specfact backlog verify-readiness --bundle <bundle-name>`
+- `specfact govern ...`
+- CI validation flows that keep the same rules active outside local development
+
+## How do I get started if I want more?
+
+**Next steps**
+
+- **[Core CLI docs](docs/index.md)** for the core runtime, bootstrap, validation, and command topology
+- **[Reference: command topology](docs/reference/commands.md)** for grouped command surfaces
+- **[Canonical modules docs site](https://modules.specfact.io/)** for bundle-deep workflows
+
+## Documentation Topology
+
+`docs.specfact.io` is the canonical starting point for SpecFact.
+
+- Core CLI/runtime/platform documentation remains owned by `specfact-cli`.
+- Module-specific deep docs are canonically owned by `specfact-cli-modules`.
+- The live modules docs site is published at `https://modules.specfact.io/`.
+
+Use this repository's docs for the overall product story, runtime lifecycle, command topology,
+trust model, and getting-started flow. Use the modules docs site when you want deeper workflow,
+adapter, and module-authoring guidance.
+
 ### Migration Note (Flat Commands Removed)
 
 As of `0.40.0`, flat root commands are removed. Use grouped commands:
@@ -401,12 +501,6 @@ For GitHub, replace adapter/org/project with:
 /specfact.01-import my-project --repo .
 ```
 
-**Next steps**
-
-- **[Core CLI docs](docs/index.md)**
-- **[Reference: command topology](docs/reference/commands.md)**
-- **[Canonical modules docs site](https://modules.specfact.io/)**
-
 ---
 
 ## Who It Is For

{specfact_cli-0.43.2 → specfact_cli-0.43.3}/README.md

@@ -1,8 +1,9 @@
 # SpecFact CLI
 
-> **The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow.**
-> Keep backlog, specs, tests, and code in sync so changes made by people or AI copilots do not break production.
-> Works for brand-new projects and long-lived codebases - even if you are new to coding.
+> **SpecFact is the validation and alignment layer for software delivery.**
+> It adds the missing validation layer that keeps backlog intent, specifications, tests, and code
+> from drifting apart across AI-assisted coding, brownfield systems, and governed delivery.
+> Use it to move fast without losing rigor.
 
 **No API keys required. Works offline. Zero vendor lock-in.**
 
@@ -23,21 +24,54 @@ invoke SpecFact as part of a command chain.
 
 ---
 
-## Documentation Topology
+## What is SpecFact?
 
-`docs.specfact.io` is the canonical docs entry point for SpecFact.
+SpecFact is the validation and alignment layer for software delivery.
 
-- Core CLI/runtime/platform documentation remains owned by `specfact-cli`.
-- Module-specific deep docs are canonically owned by `specfact-cli-modules`.
-- The live modules docs site is currently published at `https://modules.specfact.io/`.
+It is a local CLI that helps you keep the intent behind a change aligned from
+backlog or idea through specifications, implementation, and checks. The “Swiss-knife CLI” metaphor
+fits because SpecFact gives you a set of focused tools for specific delivery problems, not a vague
+bag of features.
 
-Use this repository's docs for the overall SpecFact workflow, CLI runtime lifecycle, module registry, trust model, and command-group topology.
-Use the modules docs site for bundle-specific deep dives, adapter details, workflow tutorials, and module-authoring guidance.
-In short, module-specific deep docs are canonically owned by `specfact-cli-modules`.
+In practice, SpecFact helps you:
+- add guardrails to AI-assisted and fast-moving greenfield work
+- reverse-engineer large brownfield codebases into trustworthy structured understanding
+- reduce the “I wanted X but got Y” drift between backlog, spec, and implementation
+- move from local rigor toward team and enterprise policy enforcement
 
----
+## Why does it exist?
+
+Modern delivery drifts in predictable ways:
+- AI-generated quick wins often lack the validation layer needed for mid- and long-term reliability
+- brownfield systems often have missing or drifted specs, so teams need to reverse-engineer reality
+- backlog intent gets reinterpreted into something else before it reaches code
+- teams working with different skill levels, opinions, and AI IDE setups need consistent review and
+  policy enforcement
+
+SpecFact exists to reduce that drift. It helps teams understand what is really there, express what
+should happen more accurately, and validate that the result still matches the original intent.
+
+## Why should I use it?
+
+Use SpecFact if you want one of these outcomes:
+- ship AI-assisted changes faster without accepting fragile “looks fine to me” quality
+- understand a legacy or unfamiliar codebase before changing it
+- hand brownfield insight into OpenSpec, Spec-Kit, or other spec-first workflows
+- keep backlog expectations, specifications, and implementation from silently diverging
+- enforce shared rules consistently across developers and CI/CD
 
-## Start Here (60 seconds)
+## What do I get?
+
+With SpecFact, you get:
+- a deterministic local CLI instead of another opaque SaaS dependency
+- a validation layer around fast-moving implementation work
+- codebase analysis and sidecar flows for brownfield understanding
+- stronger backlog/spec/code alignment for real delivery workflows
+- a path from individual rigor to organization-level policy enforcement
+
+## How do I get started?
+
+### Start Here (5 minutes)
 
 ### Install
 
@@ -49,38 +83,104 @@ uvx specfact-cli@latest
 pip install -U specfact-cli
 ```
 
-### Bootstrap and IDE Setup
+### Bootstrap
 
 ```bash
-# First run: install official bundles
+# Recommended first run
 specfact init --profile solo-developer
-
-# Alternative bundle selection
-specfact init --install backlog,codebase
-specfact init --install all
-
-# IDE prompt/template setup
-specfact init ide
-specfact init ide --ide cursor
-specfact init ide --ide vscode
 ```
 
-`specfact init ide` discovers prompt resources from installed workflow modules and exports them to your IDE. If module prompt payloads are not installed yet, the CLI uses packaged fallback resources.
-
-### Run Your First Flow
+### Get First Value
 
 ```bash
-# Analyze an existing codebase
+# Analyze a codebase you care about
 specfact code import my-project --repo .
 
-# Snapshot current project state
+# Snapshot the project state for follow-up workflows
 specfact project snapshot --bundle my-project
 
-# Validate external code without modifying source
+# Validate external code without modifying the target repo
 specfact code validate sidecar init my-project /path/to/repo
 specfact code validate sidecar run my-project /path/to/repo
 ```
 
+That path gives you a concrete first win: SpecFact understands your project context and gives you a
+validated starting point instead of jumping straight into blind change work.
+
+### AI IDE Setup
+
+```bash
+specfact init ide
+specfact init ide --ide cursor
+specfact init ide --ide vscode
+```
+
+`specfact init ide` discovers prompt resources from installed workflow modules and exports them to
+your IDE. If module prompt payloads are not installed yet, the CLI uses packaged fallback resources.
+
+## Choose Your Path
+
+### Greenfield and AI-assisted delivery
+
+Use SpecFact as the validation layer around fast-moving implementation work.
+
+Start with:
+- `specfact init --profile solo-developer`
+- `specfact code validate sidecar init <bundle> /path/to/repo`
+- `specfact code validate sidecar run <bundle> /path/to/repo`
+
+### Brownfield and reverse engineering
+
+Use SpecFact to understand an existing system before you change it, then hand that understanding
+into spec-first tools such as OpenSpec or Spec-Kit.
+
+Start with:
+- `specfact code import my-project --repo .`
+- `specfact project snapshot --bundle my-project`
+- `specfact code validate sidecar init my-project /path/to/repo`
+- `specfact code validate sidecar run my-project /path/to/repo`
+
+### Backlog to code alignment
+
+Use SpecFact when the problem is not only code quality, but drift between expectations and delivery.
+Backlog commands require a backlog-enabled profile or installed backlog bundle before the workflow
+commands are available.
+
+Start with:
+- `specfact init --profile backlog-team`
+- `specfact backlog ceremony standup ...`
+- `specfact backlog ceremony refinement ...`
+- `specfact backlog verify-readiness --bundle <bundle-name>`
+
+### Team and policy enforcement
+
+Use SpecFact when multiple developers and AI IDEs need consistent checks and review behavior.
+
+Start with:
+- `specfact backlog verify-readiness --bundle <bundle-name>`
+- `specfact govern ...`
+- CI validation flows that keep the same rules active outside local development
+
+## How do I get started if I want more?
+
+**Next steps**
+
+- **[Core CLI docs](docs/index.md)** for the core runtime, bootstrap, validation, and command topology
+- **[Reference: command topology](docs/reference/commands.md)** for grouped command surfaces
+- **[Canonical modules docs site](https://modules.specfact.io/)** for bundle-deep workflows
+
+## Documentation Topology
+
+`docs.specfact.io` is the canonical starting point for SpecFact.
+
+- Core CLI/runtime/platform documentation remains owned by `specfact-cli`.
+- Module-specific deep docs are canonically owned by `specfact-cli-modules`.
+- The live modules docs site is published at `https://modules.specfact.io/`.
+
+Use this repository's docs for the overall product story, runtime lifecycle, command topology,
+trust model, and getting-started flow. Use the modules docs site when you want deeper workflow,
+adapter, and module-authoring guidance.
+
 ### Migration Note (Flat Commands Removed)
 
 As of `0.40.0`, flat root commands are removed. Use grouped commands:
@@ -120,12 +220,6 @@ For GitHub, replace adapter/org/project with:
 /specfact.01-import my-project --repo .
 ```
 
-**Next steps**
-
-- **[Core CLI docs](docs/index.md)**
-- **[Reference: command topology](docs/reference/commands.md)**
-- **[Canonical modules docs site](https://modules.specfact.io/)**
-
 ---
 
 ## Who It Is For

{specfact_cli-0.43.2 → specfact_cli-0.43.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.43.2"
+version = "0.43.3"
 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"

{specfact_cli-0.43.2 → specfact_cli-0.43.3}/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.43.2"
+__version__ = "0.43.3"

{specfact_cli-0.43.2 → specfact_cli-0.43.3}/src/specfact_cli/__init__.py

@@ -45,6 +45,6 @@ def _bootstrap_bundle_paths() -> None:
 
 _bootstrap_bundle_paths()
 
-__version__ = "0.43.2"
+__version__ = "0.43.3"
 
 __all__ = ["__version__"]

{specfact_cli-0.43.2 → specfact_cli-0.43.3}/src/specfact_cli/utils/acceptance_criteria.py

@@ -30,9 +30,18 @@ _COMMON_WORD_TOKENS = frozenset(
 )
 
 
+def _contains_disallowed_control_chars(text: str) -> bool:
+    """Return whether text contains control characters beyond normal whitespace."""
+
+    return any(ord(char) < 32 and char not in "\n\r\t" for char in text)
+
+
 def _code_pattern_match_is_meaningful(pattern: str, acceptance: str) -> bool:
     """Return True if regex matches are not only common English words."""
-    matches = re.findall(pattern, acceptance, re.IGNORECASE)
+    try:
+        matches = re.findall(pattern, acceptance, re.IGNORECASE)
+    except re.error:
+        return False
     if isinstance(matches, list):
         actual = [m for m in matches if isinstance(m, str) and m.lower() not in _COMMON_WORD_TOKENS]
     else:
@@ -61,6 +70,8 @@ def is_simplified_format_criteria(acceptance: str) -> bool:
     Returns:
         True if criteria use the simplified format, False otherwise
     """
+    if _contains_disallowed_control_chars(acceptance):
+        return False
     acceptance_lower = acceptance.lower()
 
     # Pattern: "Must verify ... works correctly (see contract examples)"
@@ -73,7 +84,13 @@ def is_simplified_format_criteria(acceptance: str) -> bool:
         r"check.*works\s+correctly.*\(see\s+contract",
     ]
 
-    return any(re.search(pattern, acceptance_lower) for pattern in simplified_patterns)
+    for pattern in simplified_patterns:
+        try:
+            if re.search(pattern, acceptance_lower):
+                return True
+        except re.error:
+            return False
+    return False
 
 
 @beartype
@@ -97,6 +114,8 @@ def is_code_specific_criteria(acceptance: str) -> bool:
     Returns:
         True if criteria are code-specific, False if vague/generic
     """
+    if _contains_disallowed_control_chars(acceptance):
+        return False
     acceptance_lower = acceptance.lower()
 
     # FIRST: Check for generic placeholders that indicate non-code-specific
@@ -123,8 +142,12 @@ def is_code_specific_criteria(acceptance: str) -> bool:
         r"\bis\s+complete\b",
         r"\bis\s+ready\b",
     ]
-    if any(re.search(pattern, acceptance_lower) for pattern in vague_patterns):
-        return False  # Not code-specific, should be enriched
+    for pattern in vague_patterns:
+        try:
+            if re.search(pattern, acceptance_lower):
+                return False  # Not code-specific, should be enriched
+        except re.error:
+            return False
 
     # THIRD: Check for code-specific indicators
     code_specific_patterns = [
@@ -161,7 +184,11 @@ def is_code_specific_criteria(acceptance: str) -> bool:
     ]
 
     for pattern in code_specific_patterns:
-        if re.search(pattern, acceptance, re.IGNORECASE) and _code_pattern_match_is_meaningful(pattern, acceptance):
+        try:
+            matched = re.search(pattern, acceptance, re.IGNORECASE)
+        except re.error:
+            return False
+        if matched and _code_pattern_match_is_meaningful(pattern, acceptance):
             return True
 
     return False