specfact-cli 0.4.2__py3-none-any.whl → 0.6.8__py3-none-any.whl

specfact_cli/models/plan.py

@@ -26,6 +26,14 @@ class Story(BaseModel):
     tasks: list[str] = Field(default_factory=list, description="Implementation tasks (methods, functions)")
     confidence: float = Field(default=1.0, ge=0.0, le=1.0, description="Confidence score (0.0-1.0)")
     draft: bool = Field(default=False, description="Whether this is a draft story")
+    scenarios: dict[str, list[str]] | None = Field(
+        None,
+        description="Scenarios extracted from control flow: primary, alternate, exception, recovery (Given/When/Then format)",
+    )
+    contracts: dict[str, Any] | None = Field(
+        None,
+        description="API contracts extracted from function signatures: parameters, return_type, preconditions, postconditions, error_contracts",
+    )
 
 
 class Feature(BaseModel):
@@ -84,6 +92,39 @@ class Metadata(BaseModel):
     stage: str = Field(default="draft", description="Plan stage (draft, review, approved, released)")
     promoted_at: str | None = Field(None, description="ISO timestamp of last promotion")
     promoted_by: str | None = Field(None, description="User who performed last promotion")
+    analysis_scope: str | None = Field(
+        None, description="Analysis scope: 'full' for entire repository, 'partial' for subdirectory analysis"
+    )
+    entry_point: str | None = Field(None, description="Entry point path for partial analysis (relative to repo root)")
+    external_dependencies: list[str] = Field(
+        default_factory=list, description="List of external modules/packages imported from outside entry point"
+    )
+
+
+class Clarification(BaseModel):
+    """Single clarification Q&A."""
+
+    id: str = Field(..., description="Unique question ID (e.g., Q001)")
+    category: str = Field(..., description="Taxonomy category (Functional Scope, Data Model, etc.)")
+    question: str = Field(..., description="Clarification question")
+    answer: str = Field(..., description="User-provided answer")
+    integrated_into: list[str] = Field(
+        default_factory=list, description="Plan sections updated (e.g., 'features.FEATURE-001.acceptance')"
+    )
+    timestamp: str = Field(..., description="ISO timestamp of answer")
+
+
+class ClarificationSession(BaseModel):
+    """Session of clarifications."""
+
+    date: str = Field(..., description="Session date (YYYY-MM-DD)")
+    questions: list[Clarification] = Field(default_factory=list, description="Questions asked in this session")
+
+
+class Clarifications(BaseModel):
+    """Plan bundle clarifications."""
+
+    sessions: list[ClarificationSession] = Field(default_factory=list, description="Clarification sessions")
 
 
 class PlanBundle(BaseModel):
@@ -95,3 +136,4 @@ class PlanBundle(BaseModel):
     product: Product = Field(..., description="Product definition")
     features: list[Feature] = Field(default_factory=list, description="Product features")
     metadata: Metadata | None = Field(None, description="Plan bundle metadata")
+    clarifications: Clarifications | None = Field(None, description="Plan clarifications (Q&A sessions)")

specfact_cli/resources/mappings/node-async.yaml

@@ -0,0 +1,49 @@
+# Node.js/TypeScript async anti-pattern detection rules
+
+# Promise patterns to detect
+promise_patterns:
+  # Unhandled promise rejections
+  - pattern: "new Promise(.*) without catch"
+    severity: HIGH
+    message: "Promise created without error handling"
+
+  # Missing await
+  - pattern: "Promise.* without await"
+    severity: MEDIUM
+    message: "Promise not awaited"
+
+  # Promise.all without error handling
+  - pattern: "Promise.all(.*) without catch"
+    severity: HIGH
+    message: "Promise.all without error handling"
+
+# Async/await patterns
+async_await:
+  # Blocking in async function
+  - pattern: "fs.readFileSync(.*) in async function"
+    severity: HIGH
+    message: "Blocking file operation in async function, use fs.readFile instead"
+
+  # Serial async operations that could be parallel
+  - pattern: "sequential await that could be parallel"
+    severity: LOW
+    message: "Consider using Promise.all for parallel operations"
+
+# Event emitter patterns
+events:
+  # Missing error event handler
+  - pattern: "EventEmitter without error handler"
+    severity: MEDIUM
+    message: "EventEmitter missing error event handler"
+
+# Callback patterns (legacy)
+callbacks:
+  # Callback hell
+  - pattern: "deeply nested callbacks"
+    severity: MEDIUM
+    message: "Consider using async/await instead of callbacks"
+
+  # Missing error-first callback
+  - pattern: "callback without error parameter"
+    severity: LOW
+    message: "Callback should follow error-first pattern"

specfact_cli/resources/mappings/python-async.yaml

@@ -0,0 +1,47 @@
+# Python async anti-pattern detection rules
+
+# Async function patterns to detect
+async_patterns:
+  # Fire-and-forget tasks (missing await)
+  - pattern: "asyncio.create_task(.*) without await"
+    severity: HIGH
+    message: "Task created but never awaited"
+
+  # Blocking calls in async functions
+  - pattern: "time.sleep(.*) in async function"
+    severity: HIGH
+    message: "Blocking sleep in async function, use asyncio.sleep instead"
+
+  # Missing error handling
+  - pattern: "await .* without try/except"
+    severity: MEDIUM
+    message: "Async call without error handling"
+
+  # Long-running tasks without timeout
+  - pattern: "await .* without timeout"
+    severity: MEDIUM
+    message: "Async operation without timeout"
+
+# Event loop patterns
+event_loop:
+  # Multiple event loops
+  - pattern: "asyncio.new_event_loop()"
+    severity: MEDIUM
+    message: "Creating new event loop, prefer asyncio.get_event_loop()"
+
+  # Blocking operations on event loop
+  - pattern: "loop.run_until_complete(.*) in async context"
+    severity: HIGH
+    message: "Blocking event loop with run_until_complete"
+
+# Protocol violations
+protocols:
+  # State transitions without validation
+  - pattern: "state change without validation"
+    severity: HIGH
+    message: "State transition without protocol validation"
+
+  # Missing guards
+  - pattern: "transition without guard check"
+    severity: MEDIUM
+    message: "State transition missing guard validation"

specfact_cli/resources/mappings/speckit-default.yaml

@@ -0,0 +1,82 @@
+# Default Spec-Kit to SpecFact CLI mapping
+#
+# This mapping defines how Spec-Kit artifacts are converted to SpecFact format
+# and vice versa. Spec-Kit uses markdown artifacts (spec.md, plan.md, tasks.md)
+# while SpecFact uses YAML plan bundles.
+#
+# Spec-Kit Format Compatibility:
+# - spec.md: Frontmatter, INVSEST criteria, Scenarios (Primary/Alternate/Exception/Recovery)
+# - plan.md: Constitution Check, Phases (Phase 0/1/2/-1), Technology Stack, Constraints, Unknowns
+# - tasks.md: Phase organization (Phase 1: Setup, Phase 2: Foundational, Phase 3+: Stories), Parallel markers [P]
+
+# Directory structure mapping
+directories:
+  spec: contracts/protocols
+  schemas: src/schemas
+  workflows: .github/workflows
+  docs: docs
+  # Spec-Kit structure: .specify/specs/[###-feature-name]/spec.md, plan.md, tasks.md
+
+# File mapping
+files:
+  components.yaml: contracts/protocols/workflow.protocol.yaml
+  architecture.md: docs/architecture.md
+  # Spec-Kit files: spec.md, plan.md, tasks.md, constitution.md
+
+# State mapping (Spec-Kit → SpecFact)
+states:
+  # Map common Spec-Kit state names to SpecFact conventions
+  initial: INIT
+  planning: PLANNING
+  implementation: IMPLEMENTATION
+  review: REVIEW
+  done: DONE
+  completed: COMPLETED
+  failed: FAILED
+
+# Event mapping
+events:
+  # Map common event names
+  start: start
+  approve: approve
+  reject: reject
+  complete: complete
+  fail: fail
+
+# Feature extraction rules
+features:
+  # Extract features from Spec-Kit structure
+  from_directories: true
+  from_issues: true
+  from_commits: true
+  confidence_threshold: 0.5
+  # Spec-Kit format: Features are in spec.md with User Stories, INVSEST criteria, Scenarios
+  # Each feature directory contains spec.md, plan.md, tasks.md
+
+# Story extraction rules
+stories:
+  # Extract stories from test files
+  from_tests: true
+  test_patterns:
+    - "test_*.py"
+    - "test_*.ts"
+    - "test_*.js"
+    - "*.spec.ts"
+    - "*.spec.js"
+  # Extract from commit messages
+  from_commits: true
+  commit_patterns:
+    - "STORY-\\d+"
+    - "story/.*"
+  # Spec-Kit format: Stories are in spec.md with:
+  # - Priority (P1/P2/P3)
+  # - INVSEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
+  # - Scenarios (Primary, Alternate, Exception, Recovery)
+  # - "Why this priority" text
+
+# Schema conversion
+schemas:
+  # Convert JSON Schema to Pydantic
+  json_schema_to_pydantic: true
+  # Convert OpenAPI to Pydantic
+  openapi_to_pydantic: true

specfact_cli/resources/prompts/specfact-enforce.md

@@ -0,0 +1,185 @@
+---
+description: "Configure quality gates and enforcement modes for contract validation"
+---
+
+# SpecFact Enforce Command
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## ⚠️ CRITICAL: CLI Usage Enforcement
+
+**YOU MUST ALWAYS USE THE SPECFACT CLI**. Never create artifacts directly.
+
+### Rules
+
+1. **ALWAYS execute CLI first**: Run `specfact enforce stage` before any analysis - execute the CLI command before any other operations
+2. **NEVER write code**: Do not implement enforcement configuration logic - the CLI handles this
+3. **NEVER create YAML/JSON directly**: All enforcement configuration must be CLI-generated
+4. **NEVER bypass CLI validation**: CLI ensures schema compliance and metadata - use it, don't bypass its validation
+5. **Use CLI output as grounding**: Parse CLI output, don't regenerate or recreate it - use the CLI output as the source of truth
+6. **NEVER manipulate internal code**: Do NOT use Python code to directly modify EnforcementConfig objects or any internal data structures. The CLI is THE interface - use it exclusively.
+7. **No internal knowledge required**: You should NOT need to know about internal implementation details (EnforcementConfig model, EnforcementPreset enum, etc.). All operations must be performed via CLI commands.
+8. **NEVER read artifacts directly**: Do NOT read enforcement configuration files directly to extract information unless for display purposes. Use CLI commands to get configuration information.
+
+### What Happens If You Don't Follow This
+
+- ❌ Artifacts may not match CLI schema versions
+- ❌ Missing metadata and telemetry
+- ❌ Format inconsistencies
+- ❌ Validation failures
+- ❌ Works only in Copilot mode, fails in CI/CD
+- ❌ Breaks when CLI internals change
+- ❌ Requires knowledge of internal code structure
+
+## ⏸️ Wait States: User Input Required
+
+**When user input is required, you MUST wait for the user's response.**
+
+### Wait State Rules
+
+1. **Never assume**: If input is missing, ask and wait
+2. **Never continue**: Do not proceed until user responds
+3. **Be explicit**: Clearly state what information you need
+4. **Provide options**: Give examples or default suggestions
+
+## Goal
+
+Configure quality gates and enforcement modes for contract validation. This command sets the enforcement preset that determines how contract violations are handled (minimal, balanced, strict).
+
+## Operating Constraints
+
+**STRICTLY READ-WRITE**: This command modifies enforcement configuration. All updates must be performed by the specfact CLI.
+
+**Command**: `specfact enforce stage`
+
+**Mode Auto-Detection**: The CLI automatically detects operational mode (CI/CD or CoPilot) based on environment. No need to specify `--mode` flag.
+
+## What This Command Does
+
+The `specfact enforce stage` command:
+
+1. **Validates** the preset value (minimal, balanced, strict)
+2. **Creates** enforcement configuration from preset
+3. **Displays** configuration summary as a table
+4. **Saves** configuration to `.specfact/config/enforcement.yaml`
+5. **Reports** configuration path and status
+
+## Execution Steps
+
+### 1. Parse Arguments and Validate Input
+
+**Parse user input** to extract:
+
+- Preset (optional, default: `balanced`)
+  - Valid values: `minimal`, `balanced`, `strict`
+
+**WAIT STATE**: If user wants to set enforcement but hasn't specified preset, ask:
+
+```text
+"Which enforcement preset would you like to use?
+- minimal: Log violations, never block
+- balanced: Block HIGH severity, warn MEDIUM (default)
+- strict: Block all MEDIUM+ violations
+
+Enter preset (minimal/balanced/strict):
+[WAIT FOR USER RESPONSE - DO NOT CONTINUE]"
+```
+
+### 2. Execute Enforce Stage Command
+
+**Execute CLI command**:
+
+```bash
+# Use default (balanced)
+specfact enforce stage
+
+# Specify preset
+specfact enforce stage --preset minimal
+specfact enforce stage --preset balanced
+specfact enforce stage --preset strict
+```
+
+**Capture from CLI**:
+
+- Preset validation (must be minimal, balanced, or strict)
+- Configuration created from preset
+- Configuration summary table displayed
+- Configuration saved to `.specfact/config/enforcement.yaml`
+
+### 3. Handle Errors
+
+**Common errors**:
+
+- **Unknown preset**: CLI will report error and list valid presets
+- **Invalid preset format**: CLI will validate and report error
+
+### 4. Report Completion
+
+**After successful execution**:
+
+```markdown
+✓ Enforcement mode set successfully!
+
+**Preset**: balanced
+**Configuration**: `.specfact/config/enforcement.yaml`
+
+**Enforcement Summary**:
+
+| Severity | Action |
+|----------|--------|
+| HIGH     | Block  |
+| MEDIUM   | Warn   |
+| LOW      | Log    |
+
+**Next Steps**:
+- Run validation: `/specfact-cli/specfact-repro`
+- Review configuration: Check `.specfact/config/enforcement.yaml`
+```
+
+## Guidelines
+
+### Enforcement Presets
+
+**minimal**:
+
+- Log all violations
+- Never block execution
+- Best for: Development, exploration, learning
+
+**balanced** (default):
+
+- Block HIGH severity violations
+- Warn on MEDIUM severity violations
+- Log LOW severity violations
+- Best for: Most production use cases
+
+**strict**:
+
+- Block all MEDIUM+ severity violations
+- Log LOW severity violations
+- Best for: Critical systems, compliance requirements
+
+### Configuration Location
+
+- Configuration is saved to: `.specfact/config/enforcement.yaml`
+- This file is automatically created/updated by the CLI
+- Configuration persists across sessions
+
+### Best Practices
+
+- Start with `balanced` preset for most use cases
+- Use `minimal` during development to avoid blocking
+- Use `strict` for production deployments or compliance
+- Review configuration file to understand exact behavior
+
+## Context
+
+{ARGS}
+
+--- End Command ---