specfact-cli 0.11.3__tar.gz → 0.11.5__tar.gz

{specfact_cli-0.11.3 → specfact_cli-0.11.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.11.3
+Version: 0.11.5
 Summary: Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git

{specfact_cli-0.11.3 → specfact_cli-0.11.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.11.3"
+version = "0.11.5"
 description = "Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -536,6 +536,7 @@ markers = [
     "state_transition_coverage: mark test for state transition coverage tracking",
 ]
 filterwarnings = [ # From pytest.ini
+    "ignore::UserWarning:rich.live",  # Filter Rich library warnings about ipywidgets (not needed for CLI tests)
     "ignore::pytest.PytestAssertRewriteWarning",
     "ignore::pytest.PytestDeprecationWarning",
 ]

{specfact_cli-0.11.3 → specfact_cli-0.11.5}/resources/prompts/shared/cli-enforcement.md

@@ -23,9 +23,12 @@
 ## Available CLI Commands
 
 - `specfact plan init <bundle-name>` - Initialize project bundle
-- `specfact import from-code <bundle-name> --repo <path>` - Import from codebase
-- `specfact plan review <bundle-name>` - Review plan
-- `specfact plan harden <bundle-name>` - Create SDD manifest
-- `specfact enforce sdd <bundle-name>` - Validate SDD
+- `specfact plan select <bundle-name>` - Set active plan (used as default for other commands)
+- `specfact import from-code [<bundle-name>] --repo <path>` - Import from codebase (uses active plan if bundle not specified)
+- `specfact plan review [<bundle-name>]` - Review plan (uses active plan if bundle not specified)
+- `specfact plan harden [<bundle-name>]` - Create SDD manifest (uses active plan if bundle not specified)
+- `specfact enforce sdd [<bundle-name>]` - Validate SDD (uses active plan if bundle not specified)
 - `specfact sync bridge --adapter <adapter> --repo <path>` - Sync with external tools
 - See [Command Reference](../../docs/reference/commands.md) for full list
+
+**Note**: Most commands now support active plan fallback. If `--bundle` is not specified, commands automatically use the active plan set via `plan select`. This improves workflow efficiency in AI IDE environments.

{specfact_cli-0.11.3 → specfact_cli-0.11.5}/resources/prompts/specfact.01-import.md

@@ -14,27 +14,25 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Purpose
 
-Import codebase → plan bundle. CLI extracts (routes, schemas, relationships, contracts). LLM enriches (context, "why", completeness).
+Import codebase → plan bundle. CLI extracts routes/schemas/relationships/contracts. LLM enriches context/"why"/completeness.
 
 ## Parameters
 
-**Target/Input**: `--bundle NAME` (required), `--repo PATH`, `--entry-point PATH`, `--enrichment PATH`  
+**Target/Input**: `--bundle NAME` (optional, defaults to active plan), `--repo PATH`, `--entry-point PATH`, `--enrichment PATH`  
 **Output/Results**: `--report PATH`  
 **Behavior/Options**: `--shadow-only`, `--enrich-for-speckit`  
 **Advanced/Configuration**: `--confidence FLOAT` (0.0-1.0), `--key-format FORMAT` (classname|sequential)
 
 ## Workflow
 
-1. **Execute CLI**: `specfact import from-code <bundle> --repo <path> [options]`
-
-   CLI extracts (no AI): routes (FastAPI/Flask/Django), schemas (Pydantic), relationships (imports/deps), contracts (OpenAPI scaffolds), source tracking, bundle metadata.
+1. **Execute CLI**: `specfact import from-code [<bundle>] --repo <path> [options]`
+   - CLI extracts: routes (FastAPI/Flask/Django), schemas (Pydantic), relationships, contracts (OpenAPI scaffolds), source tracking
+   - Uses active plan if bundle not specified
 
 2. **LLM Enrichment** (if `--enrichment` provided):
-   - **Context file**: Read `.specfact/projects/<bundle>/enrichment_context.md` for relationships, contracts, schemas
-   - Use CLI output + bundle metadata + enrichment context as context
+   - Read `.specfact/projects/<bundle>/enrichment_context.md`
    - Enrich: business context, "why" reasoning, missing acceptance criteria
    - Validate: contracts vs code, feature/story alignment
-   - Complete: constraints, test scenarios, edge cases
 
 3. **Present**: Bundle location, report path, summary (features/stories/contracts/relationships)
 
@@ -50,10 +48,10 @@ Import codebase → plan bundle. CLI extracts (routes, schemas, relationships, c
 ## Common Patterns
 
 ```bash
+/specfact.01-import --repo .                    # Uses active plan
 /specfact.01-import --bundle legacy-api --repo .
-/specfact.01-import --bundle legacy-api --repo . --enrichment report.md
-/specfact.01-import --bundle auth-module --repo . --entry-point src/auth/
-/specfact.01-import --bundle legacy-api --repo . --enrich-for-speckit
+/specfact.01-import --repo . --entry-point src/auth/
+/specfact.01-import --repo . --enrichment report.md
 ```
 
 ## Context

specfact_cli-0.11.5/resources/prompts/specfact.02-plan.md

@@ -0,0 +1,117 @@
+---
+description: Manage project bundles - create, add features/stories, and update plan metadata.
+---
+
+# SpecFact Plan Management Command
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Manage project bundles: initialize, add features/stories, update metadata (idea/features/stories).
+
+**When to use:** Creating bundles, adding features/stories, updating metadata.
+
+**Quick:** `/specfact.02-plan init legacy-api` or `/specfact.02-plan add-feature --key FEATURE-001 --title "User Auth"`
+
+## Parameters
+
+### Target/Input
+
+- `--bundle NAME` - Project bundle name (optional, defaults to active plan set via `plan select`)
+- `--key KEY` - Feature/story key (e.g., FEATURE-001, STORY-001)
+- `--feature KEY` - Parent feature key (for story operations)
+
+### Output/Results
+
+- (No output-specific parameters for plan management)
+
+### Behavior/Options
+
+- `--interactive/--no-interactive` - Interactive mode. Default: True (interactive)
+- `--scaffold/--no-scaffold` - Create directory structure. Default: True (scaffold enabled)
+
+### Advanced/Configuration
+
+- `--title TEXT` - Feature/story title
+- `--outcomes TEXT` - Expected outcomes (comma-separated)
+- `--acceptance TEXT` - Acceptance criteria (comma-separated)
+- `--constraints TEXT` - Constraints (comma-separated)
+- `--confidence FLOAT` - Confidence score (0.0-1.0)
+- `--draft/--no-draft` - Mark as draft
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+- Determine operation: `init`, `add-feature`, `add-story`, `update-idea`, `update-feature`, `update-story`
+- Extract parameters (bundle name defaults to active plan if not specified, keys, etc.)
+
+### Step 2: Execute CLI
+
+```bash
+specfact plan init <bundle-name> [--interactive/--no-interactive] [--scaffold/--no-scaffold]
+specfact plan add-feature [--bundle <name>] --key <key> --title <title> [--outcomes <outcomes>] [--acceptance <acceptance>]
+specfact plan add-story [--bundle <name>] --feature <feature-key> --key <story-key> --title <title> [--acceptance <acceptance>]
+specfact plan update-idea [--bundle <name>] [--title <title>] [--narrative <narrative>] [--target-users <users>] [--value-hypothesis <hypothesis>] [--constraints <constraints>]
+specfact plan update-feature [--bundle <name>] --key <key> [--title <title>] [--outcomes <outcomes>] [--acceptance <acceptance>] [--constraints <constraints>] [--confidence <score>] [--draft/--no-draft]
+specfact plan update-story [--bundle <name>] --feature <feature-key> --key <story-key> [--title <title>] [--acceptance <acceptance>] [--story-points <points>] [--value-points <points>] [--confidence <score>] [--draft/--no-draft]
+# --bundle defaults to active plan if not specified
+```
+
+### Step 3: Present Results
+
+- Display bundle location
+- Show created/updated features/stories
+- Present summary of changes
+
+## CLI Enforcement
+
+**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
+
+**Rules:** Execute CLI first, use `--no-interactive` in CI/CD, never modify `.specfact/` directly, use CLI output as grounding.
+
+## Expected Output
+
+## Success (Init)
+
+```text
+✓ Project bundle created: .specfact/projects/legacy-api/
+✓ Bundle initialized with scaffold structure
+```
+
+## Success (Add Feature)
+
+```text
+✓ Feature 'FEATURE-001' added successfully
+Feature: User Authentication
+Outcomes: Secure login, Session management
+```
+
+## Error (Missing Bundle)
+
+```text
+✗ Project bundle name is required (or set active plan with 'plan select')
+Usage: specfact plan <operation> [--bundle <name>] [options]
+```
+
+## Common Patterns
+
+```bash
+/specfact.02-plan init legacy-api
+/specfact.02-plan add-feature --key FEATURE-001 --title "User Auth" --outcomes "Secure login" --acceptance "Users can log in"
+/specfact.02-plan add-story --feature FEATURE-001 --key STORY-001 --title "Login API" --acceptance "API returns JWT"
+/specfact.02-plan update-feature --key FEATURE-001 --title "Updated Title" --confidence 0.9
+/specfact.02-plan update-idea --target-users "Developers, DevOps" --value-hypothesis "Reduce technical debt"
+# --bundle defaults to active plan if not specified
+```
+
+## Context
+
+{ARGS}

specfact_cli-0.11.5/resources/prompts/specfact.03-review.md

@@ -0,0 +1,220 @@
+---
+description: Review project bundle to identify ambiguities, resolve gaps, and prepare for promotion.
+---
+
+# SpecFact Review Command
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Review project bundle to identify/resolve ambiguities and missing information. Asks targeted questions for promotion readiness.
+
+**When to use:** After import/creation, before promotion, when clarification needed.
+
+**Quick:** `/specfact.03-review` (uses active plan) or `/specfact.03-review legacy-api`
+
+## Parameters
+
+### Target/Input
+
+- `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`)
+- `--category CATEGORY` - Focus on specific taxonomy category. Default: None (all categories)
+
+### Output/Results
+
+- `--list-questions` - Output questions in JSON format. Default: False
+- `--list-findings` - Output all findings in structured format. Default: False
+- `--findings-format FORMAT` - Output format: json, yaml, or table. Default: json for non-interactive, table for interactive
+
+### Behavior/Options
+
+- `--no-interactive` - Non-interactive mode (for CI/CD). Default: False (interactive mode)
+- `--answers JSON` - JSON object with question_id -> answer mappings. Default: None
+- `--auto-enrich` - Automatically enrich vague acceptance criteria. Default: False
+
+### Advanced/Configuration
+
+- `--max-questions INT` - Maximum questions per session. Default: 5 (range: 1-10)
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+- Extract bundle name (defaults to active plan if not specified)
+- Extract optional parameters (max-questions, category, etc.)
+
+### Step 2: Execute CLI to Get Findings
+
+**First, get findings to understand what needs enrichment:**
+
+```bash
+specfact plan review [<bundle-name>] --list-findings --findings-format json
+# Uses active plan if bundle not specified
+```
+
+This outputs all ambiguities and missing information in structured format.
+
+### Step 3: Create Enrichment Report (if needed)
+
+Based on the findings, create a Markdown enrichment report that addresses:
+
+- **Business Context**: Priorities, constraints, unknowns
+- **Confidence Adjustments**: Feature confidence score updates (if needed)
+- **Missing Features**: New features to add (if any)
+- **Manual Updates**: Guidance for updating `idea.yaml` fields like `target_users`, `value_hypothesis`, `narrative`
+
+**Enrichment Report Format:**
+
+```markdown
+## Business Context
+
+### Priorities
+- Priority 1
+- Priority 2
+
+### Constraints
+- Constraint 1
+- Constraint 2
+
+### Unknowns
+- Unknown 1
+- Unknown 2
+
+## Confidence Adjustments
+
+FEATURE-KEY → 0.95
+FEATURE-OTHER → 0.8
+
+## Missing Features
+
+(If any features are missing)
+
+## Recommendations for Manual Updates
+
+### idea.yaml Updates Required
+
+**target_users:**
+- Primary: [description]
+- Secondary: [description]
+
+**value_hypothesis:**
+[Value proposition]
+
+**narrative:**
+[Improved narrative]
+```
+
+### Step 4: Apply Enrichment
+
+#### Option A: Use enrichment to answer review questions
+
+Create answers JSON from enrichment report and use with review:
+
+```bash
+specfact plan review [<bundle-name>] --answers '{"Q001": "answer1", "Q002": "answer2"}'
+```
+
+#### Option B: Update idea fields directly via CLI
+
+Use `plan update-idea` to update idea fields from enrichment recommendations:
+
+```bash
+specfact plan update-idea --bundle [<bundle-name>] --value-hypothesis "..." --narrative "..." --target-users "..."
+```
+
+#### Option C: Apply enrichment via import (only if bundle needs regeneration)
+
+```bash
+specfact import from-code [<bundle-name>] --repo . --enrichment enrichment-report.md
+```
+
+**Note:**
+
+- **Preferred**: Use Option A (answers) or Option B (update-idea) for most cases
+- Only use Option C if you need to regenerate the bundle
+- Never manually edit `.specfact/` files directly - always use CLI commands
+
+### Step 5: Present Results
+
+- Display Q&A, sections touched, coverage summary (initial/updated)
+- Note: Clarifications don't affect hash (stable across review sessions)
+- If enrichment report was created, summarize what was addressed
+
+## CLI Enforcement
+
+**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
+
+**Rules:** Execute CLI first, use `--no-interactive` in CI/CD, never modify `.specfact/` directly, use CLI output as grounding.
+
+## Expected Output
+
+### Success
+
+```text
+✓ Review complete: 5 question(s) answered
+
+Project Bundle: legacy-api
+Questions Asked: 5
+
+Sections Touched:
+  • idea.narrative
+  • features[FEATURE-001].acceptance
+  • features[FEATURE-002].outcomes
+
+Coverage Summary:
+  ✅ Functional Scope: clear
+  ✅ Technical Constraints: clear
+  ⚠️ Business Context: partial
+```
+
+### Error (Missing Bundle)
+
+```text
+✗ Project bundle 'legacy-api' not found
+Create one with: specfact plan init legacy-api
+```
+
+## Common Patterns
+
+```bash
+# Get findings first
+/specfact.03-review --list-findings                    # List all findings
+/specfact.03-review --list-findings --findings-format json  # JSON format for enrichment
+
+# Interactive review
+/specfact.03-review                                    # Uses active plan
+/specfact.03-review legacy-api                         # Specific bundle
+/specfact.03-review --max-questions 3                  # Limit questions
+/specfact.03-review --category "Functional Scope"      # Focus category
+
+# Non-interactive with answers
+/specfact.03-review --answers '{"Q001": "answer"}'     # Provide answers directly
+/specfact.03-review --list-questions                   # Output questions as JSON
+
+# Auto-enrichment
+/specfact.03-review --auto-enrich                     # Auto-enrich vague criteria
+```
+
+## Enrichment Workflow
+
+**Typical workflow when enrichment is needed:**
+
+1. **Get findings**: `specfact plan review --list-findings --findings-format json`
+2. **Analyze findings**: Review missing information (target_users, value_hypothesis, etc.)
+3. **Create enrichment report**: Write Markdown file addressing findings
+4. **Apply enrichment**:
+   - **Preferred**: Use enrichment to create `--answers` JSON and run `plan review --answers`
+   - **Alternative**: Use `plan update-idea` to update idea fields directly
+   - **Last resort**: If bundle needs regeneration, use `import from-code --enrichment`
+5. **Verify**: Run `plan review` again to confirm improvements
+
+## Context
+
+{ARGS}

specfact_cli-0.11.5/resources/prompts/specfact.04-sdd.md

@@ -0,0 +1,105 @@
+---
+description: Create or update SDD manifest (hard spec) from project bundle with WHY/WHAT/HOW extraction.
+---
+
+# SpecFact SDD Creation Command
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Create/update SDD manifest from project bundle. Captures WHY (intent/constraints), WHAT (capabilities/acceptance), HOW (architecture/invariants/contracts).
+
+**When to use:** After plan review, before promotion, when plan changes.
+
+**Quick:** `/specfact.04-sdd` (uses active plan) or `/specfact.04-sdd legacy-api`
+
+## Parameters
+
+### Target/Input
+
+- `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`)
+- `--sdd PATH` - Output SDD manifest path. Default: .specfact/sdd/<bundle-name>.<format>
+
+### Output/Results
+
+- `--output-format FORMAT` - SDD manifest format (yaml or json). Default: global --output-format (yaml)
+
+### Behavior/Options
+
+- `--interactive/--no-interactive` - Interactive mode with prompts. Default: True (interactive, auto-detect)
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+- Extract bundle name (defaults to active plan if not specified)
+- Extract optional parameters (sdd path, output format, etc.)
+
+### Step 2: Execute CLI
+
+```bash
+specfact plan harden [<bundle-name>] [--sdd <path>] [--output-format <format>]
+# Uses active plan if bundle not specified
+```
+
+### Step 3: Present Results
+
+- Display SDD location, WHY/WHAT/HOW summary, coverage metrics
+- Hash excludes clarifications (stable across review sessions)
+
+## CLI Enforcement
+
+**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
+
+**Rules:** Execute CLI first, use `--no-interactive` in CI/CD, never modify `.specfact/` directly, use CLI output as grounding.
+
+## Expected Output
+
+### Success
+
+```text
+✓ SDD manifest created: .specfact/sdd/legacy-api.yaml
+
+SDD Manifest Summary:
+Project Bundle: .specfact/projects/legacy-api/
+Bundle Hash: abc123def456...
+SDD Path: .specfact/sdd/legacy-api.yaml
+
+WHY (Intent):
+  Build secure authentication system
+Constraints: 2
+
+WHAT (Capabilities): 12
+
+HOW (Architecture):
+  Microservices architecture with JWT tokens...
+Invariants: 8
+Contracts: 15
+```
+
+### Error (Missing Bundle)
+
+```text
+✗ Project bundle 'legacy-api' not found
+Create one with: specfact plan init legacy-api
+```
+
+## Common Patterns
+
+```bash
+/specfact.04-sdd                              # Uses active plan
+/specfact.04-sdd legacy-api                   # Specific bundle
+/specfact.04-sdd --output-format json         # JSON format
+/specfact.04-sdd --sdd .specfact/sdd/custom.yaml
+```
+
+## Context
+
+{ARGS}

{specfact_cli-0.11.3 → specfact_cli-0.11.5}/resources/prompts/specfact.05-enforce.md

@@ -14,26 +14,17 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Purpose
 
-Validate SDD manifest against project bundle and contracts. Checks hash matching, coverage thresholds, frozen sections, and contract density metrics to ensure SDD is synchronized with bundle.
+Validate SDD manifest against project bundle and contracts. Checks hash matching, coverage thresholds, and contract density.
 
-**When to use:**
+**When to use:** After creating/updating SDD, before promotion, in CI/CD pipelines.
 
-- After creating or updating SDD manifest
-- Before promoting bundle to approved/released stages
-- In CI/CD pipelines for quality gates
-
-**Quick Example:**
-
-```bash
-/specfact.05-enforce legacy-api
-/specfact.05-enforce legacy-api --output-format json --out validation-report.json
-```
+**Quick:** `/specfact.05-enforce` (uses active plan) or `/specfact.05-enforce legacy-api`
 
 ## Parameters
 
 ### Target/Input
 
-- `bundle NAME` (required argument) - Project bundle name (e.g., legacy-api, auth-module)
+- `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`)
 - `--sdd PATH` - Path to SDD manifest. Default: .specfact/sdd/<bundle-name>.<format>
 
 ### Output/Results
@@ -49,17 +40,14 @@ Validate SDD manifest against project bundle and contracts. Checks hash matching
 
 ### Step 1: Parse Arguments
 
-- Extract bundle name (required)
+- Extract bundle name (defaults to active plan if not specified)
 - Extract optional parameters (sdd path, output format, etc.)
 
 ### Step 2: Execute CLI
 
 ```bash
-# Validate SDD
-specfact enforce sdd <bundle-name> [--sdd <path>] [--output-format <format>] [--out <path>]
-
-# Non-interactive validation
-specfact enforce sdd <bundle-name> --no-interactive --output-format json
+specfact enforce sdd [<bundle-name>] [--sdd <path>] [--output-format <format>] [--out <path>]
+# Uses active plan if bundle not specified
 ```
 
 ### Step 3: Present Results
@@ -74,13 +62,7 @@ specfact enforce sdd <bundle-name> --no-interactive --output-format json
 
 **CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
 
-**Rules:**
-
-1. **ALWAYS execute CLI first**: Run `specfact enforce sdd` before any analysis
-2. **ALWAYS use non-interactive mode for CI/CD**: Use `--no-interactive` flag in Copilot environments
-3. **NEVER modify .specfact folder directly**: All operations must go through CLI
-4. **NEVER create YAML/JSON directly**: All validation reports must be CLI-generated
-5. **Use CLI output as grounding**: Parse CLI output, don't regenerate it
+**Rules:** Execute CLI first, use `--no-interactive` in CI/CD, never modify `.specfact/` directly, use CLI output as grounding.
 
 ## Expected Output
 
@@ -110,29 +92,18 @@ Issues Found:
    SDD hash: abc123def456...
    Bundle hash: xyz789ghi012...
 
-   Why this happens:
-   The hash changes when you modify:
-   - Features (add/remove/update)
-   - Stories (add/remove/update)
-   - Product, idea, business, or clarifications
-
-   Fix: Run specfact plan harden legacy-api to update the SDD manifest
+   Hash changes when modifying features, stories, or product/idea/business sections.
+   Note: Clarifications don't affect hash (review metadata). Hash stable across review sessions.
+   Fix: Run `specfact plan harden <bundle-name>` to update SDD manifest.
 ```
 
 ## Common Patterns
 
 ```bash
-# Validate SDD
-/specfact.05-enforce legacy-api
-
-# Validate with JSON output
-/specfact.05-enforce legacy-api --output-format json
-
-# Validate with custom report path
-/specfact.05-enforce legacy-api --out custom-report.json
-
-# Non-interactive validation
-/specfact.05-enforce legacy-api --no-interactive
+/specfact.05-enforce                    # Uses active plan
+/specfact.05-enforce legacy-api         # Specific bundle
+/specfact.05-enforce --output-format json --out report.json
+/specfact.05-enforce --no-interactive   # CI/CD mode
 ```
 
 ## Context