specfact-cli 0.13.3__tar.gz → 0.14.2__tar.gz

{specfact_cli-0.13.3 → specfact_cli-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.13.3
+Version: 0.14.2
 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.13.3 → specfact_cli-0.14.2}/pyproject.toml

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

specfact_cli-0.14.2/resources/prompts/shared/cli-enforcement.md

@@ -0,0 +1,113 @@
+# CLI Usage Enforcement Rules
+
+## Core Principle
+
+**ALWAYS use SpecFact CLI commands. Never create artifacts directly.**
+
+## CLI vs LLM Capabilities
+
+### CLI-Only Operations (CI/CD Mode - No LLM Required)
+
+The CLI can perform these operations **without LLM**:
+
+- ✅ Tool execution (ruff, pylint, basedpyright, mypy, semgrep, specmatic)
+- ✅ Bundle management (create, load, save, validate structure)
+- ✅ Metadata management (timestamps, hashes, telemetry)
+- ✅ Planning operations (init, add-feature, add-story, update-idea, update-feature)
+- ✅ AST/Semgrep-based analysis (code structure, patterns, relationships)
+- ✅ Specmatic validation (OpenAPI/AsyncAPI contract validation)
+- ✅ Format validation (YAML/JSON schema compliance)
+- ✅ Source tracking and drift detection
+
+**CRITICAL LIMITATIONS**:
+
+- ❌ **CANNOT generate code** - No LLM available in CLI-only mode
+- ❌ **CANNOT do reasoning** - No semantic understanding without LLM
+
+### LLM-Required Operations (AI IDE Mode - Via Slash Prompts)
+
+These operations **require LLM** and are only available via AI IDE slash prompts:
+
+- ✅ Code generation (requires LLM reasoning)
+- ✅ Code enhancement (contracts, refactoring, improvements)
+- ✅ Semantic understanding (business logic, context, priorities)
+- ✅ Plan enrichment (missing features, confidence adjustments, business context)
+- ✅ Code reasoning (why decisions were made, trade-offs, constraints)
+
+**Access**: Only available via AI IDE slash prompts (Cursor, CoPilot, etc.)  
+**Pattern**: Slash prompt → LLM generates → CLI validates → Apply if valid
+
+## Rules
+
+1. **Execute CLI First**: Always run CLI commands before any analysis
+2. **Use CLI for Writes**: All write operations must go through CLI
+3. **Read for Display Only**: Use file reading tools for display/analysis only
+4. **Never Modify .specfact/**: Do not create/modify files in `.specfact/` directly
+5. **Never Bypass Validation**: CLI ensures schema compliance and metadata
+6. **Code Generation Requires LLM**: Code generation is only possible via AI IDE slash prompts, not CLI-only
+
+## Standard Validation Loop Pattern (For LLM-Generated Code)
+
+When generating or enhancing code via LLM, **ALWAYS** follow this pattern:
+
+```text
+1. CLI Prompt Generation (Required)
+   ↓
+   CLI generates structured prompt → saved to .specfact/prompts/
+   (e.g., `generate contracts-prompt`, future: `generate code-prompt`)
+
+2. LLM Execution (Required - AI IDE Only)
+   ↓
+   LLM reads prompt → generates enhanced code → writes to TEMPORARY file
+   (NEVER writes directly to original artifacts)
+   Pattern: `enhanced_<filename>.py` or `generated_<feature>.py`
+
+3. CLI Validation Loop (Required, up to N retries)
+   ↓
+   CLI validates temp file with all relevant tools:
+   - Syntax validation (py_compile)
+   - File size check (must be >= original)
+   - AST structure comparison (preserve functions/classes)
+   - Contract imports verification
+   - Code quality checks (ruff, pylint, basedpyright, mypy)
+   - Test execution (contract-test, pytest)
+   ↓
+   If validation fails:
+   - CLI provides detailed error feedback
+   - LLM fixes issues in temp file
+   - Re-validate (max 3 attempts)
+   ↓
+   If validation succeeds:
+   - CLI applies changes to original file
+   - CLI removes temporary file
+   - CLI updates metadata/telemetry
+```
+
+**This pattern must be used for**:
+
+- ✅ Contract enhancement (`generate contracts-prompt` / `contracts-apply`) - Already implemented
+- ⏳ Code generation (future: `generate code-prompt` / `code-apply`) - Needs implementation
+- ⏳ Plan enrichment (future: `plan enrich-prompt` / `enrich-apply`) - Needs implementation
+- ⏳ Any LLM-enhanced artifact modification - Needs implementation
+
+## What Happens If You Don't Follow
+
+- ❌ Artifacts may not match CLI schema versions
+- ❌ Missing metadata and telemetry
+- ❌ Format inconsistencies
+- ❌ Validation failures
+- ❌ Works only in Copilot mode, fails in CI/CD
+- ❌ Code generation attempts in CLI-only mode will fail (no LLM available)
+
+## Available CLI Commands
+
+- `specfact plan init <bundle-name>` - Initialize project bundle
+- `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.14.2/resources/prompts/specfact.01-import.md

@@ -0,0 +1,118 @@
+---
+description: Import codebase → plan bundle. CLI extracts routes/schemas/relationships. LLM enriches with context.
+---
+
+# SpecFact Import Command
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+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.
+
+## Parameters
+
+**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: 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):
+   - Read `.specfact/projects/<bundle>/enrichment_context.md`
+   - Enrich: business context, "why" reasoning, missing acceptance criteria
+   - Validate: contracts vs code, feature/story alignment
+   - Save enrichment report to `.specfact/reports/enrichment/` (if created)
+
+3. **Present**: Bundle location, report path, summary (features/stories/contracts/relationships)
+
+## CLI Enforcement
+
+**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
+
+**Rules:**
+
+- Execute CLI first - never create artifacts directly
+- Use `--no-interactive` flag in CI/CD environments
+- Never modify `.specfact/` directly
+- Use CLI output as grounding for validation
+- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only)
+
+## Dual-Stack Workflow (Copilot Mode)
+
+When in copilot mode, follow this three-phase workflow:
+
+### Phase 1: CLI Grounding (REQUIRED)
+
+```bash
+# Execute CLI to get structured output
+specfact import from-code [<bundle>] --repo <path> --no-interactive
+```
+
+**Capture**:
+
+- CLI-generated artifacts (plan bundles, reports)
+- Metadata (timestamps, confidence scores)
+- Telemetry (execution time, file counts)
+
+### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only)
+
+**Purpose**: Add semantic understanding to CLI output
+
+**What to do**:
+
+- Read CLI-generated artifacts (use file reading tools for display only)
+- Research codebase for additional context
+- Identify missing features/stories
+- Suggest confidence adjustments
+- Extract business context
+
+**What NOT to do**:
+
+- ❌ Create YAML/JSON artifacts directly
+- ❌ Modify CLI artifacts directly (use CLI commands to update)
+- ❌ Bypass CLI validation
+- ❌ Write to `.specfact/` folder directly (always use CLI)
+- ❌ Use direct file manipulation tools for writing (use CLI commands)
+
+**Output**: Generate enrichment report (Markdown) saved to `.specfact/reports/enrichment/`
+
+### Phase 3: CLI Artifact Creation (REQUIRED)
+
+```bash
+# Use enrichment to update plan via CLI
+specfact import from-code [<bundle>] --repo <path> --enrichment <enrichment-report> --no-interactive
+```
+
+**Result**: Final artifacts are CLI-generated with validated enrichments
+
+**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code))
+
+## Expected Output
+
+**Success**: Bundle location, report path, summary (features/stories/contracts/relationships)  
+**Error**: Missing bundle name or bundle already exists
+
+## Common Patterns
+
+```bash
+/specfact.01-import --repo .                    # Uses active plan
+/specfact.01-import --bundle legacy-api --repo .
+/specfact.01-import --repo . --entry-point src/auth/
+/specfact.01-import --repo . --enrichment report.md
+```
+
+## Context
+
+{ARGS}

{specfact_cli-0.13.3 → specfact_cli-0.14.2}/resources/prompts/specfact.02-plan.md

@@ -75,7 +75,65 @@ specfact plan update-story [--bundle <name>] --feature <feature-key> --key <stor
 
 **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.
+**Rules:**
+
+- Execute CLI first - never create artifacts directly
+- Use `--no-interactive` flag in CI/CD environments
+- Never modify `.specfact/` directly
+- Use CLI output as grounding for validation
+- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only)
+
+## Dual-Stack Workflow (Copilot Mode)
+
+When in copilot mode, follow this three-phase workflow:
+
+### Phase 1: CLI Grounding (REQUIRED)
+
+```bash
+# Execute CLI to get structured output
+specfact plan <operation> [--bundle <name>] [options] --no-interactive
+```
+
+**Capture**:
+
+- CLI-generated artifacts (plan bundles, features, stories)
+- Metadata (timestamps, confidence scores)
+- Telemetry (execution time, file counts)
+
+### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only)
+
+**Purpose**: Add semantic understanding to CLI output
+
+**What to do**:
+
+- Read CLI-generated artifacts (use file reading tools for display only)
+- Research codebase for additional context
+- Identify missing features/stories
+- Suggest confidence adjustments
+- Extract business context
+
+**What NOT to do**:
+
+- ❌ Create YAML/JSON artifacts directly
+- ❌ Modify CLI artifacts directly (use CLI commands to update)
+- ❌ Bypass CLI validation
+- ❌ Write to `.specfact/` folder directly (always use CLI)
+- ❌ Use direct file manipulation tools for writing (use CLI commands)
+
+**Output**: Generate enrichment report (Markdown) or use `--batch-updates` JSON/YAML file
+
+### Phase 3: CLI Artifact Creation (REQUIRED)
+
+```bash
+# Use enrichment to update plan via CLI
+specfact plan update-feature [--bundle <name>] --key <key> [options] --no-interactive
+# Or use batch updates:
+specfact plan update-feature [--bundle <name>] --batch-updates <updates.json> --no-interactive
+```
+
+**Result**: Final artifacts are CLI-generated with validated enrichments
+
+**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code))
 
 ## Expected Output
 

{specfact_cli-0.13.3 → specfact_cli-0.14.2}/resources/prompts/specfact.03-review.md

@@ -151,7 +151,63 @@ specfact import from-code [<bundle-name>] --repo . --enrichment enrichment-repor
 
 **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.
+**Rules:**
+
+- Execute CLI first - never create artifacts directly
+- Use `--no-interactive` flag in CI/CD environments
+- Never modify `.specfact/` directly
+- Use CLI output as grounding for validation
+- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only)
+
+## Dual-Stack Workflow (Copilot Mode)
+
+When in copilot mode, follow this three-phase workflow:
+
+### Phase 1: CLI Grounding (REQUIRED)
+
+```bash
+# Execute CLI to get structured output
+specfact plan review [<bundle-name>] --list-findings --findings-format json --no-interactive
+```
+
+**Capture**:
+
+- CLI-generated findings (ambiguities, missing information)
+- Structured JSON/YAML output for bulk processing
+- Metadata (timestamps, confidence scores)
+
+### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only)
+
+**Purpose**: Add semantic understanding to CLI findings
+
+**What to do**:
+
+- Read CLI-generated findings (use file reading tools for display only)
+- Research codebase for additional context
+- Generate enrichment report or batch update file
+- Address ambiguities with business context
+
+**What NOT to do**:
+
+- ❌ Create YAML/JSON artifacts directly
+- ❌ Modify CLI artifacts directly (use CLI commands to update)
+- ❌ Bypass CLI validation
+- ❌ Write to `.specfact/` folder directly (always use CLI)
+
+**Output**: Generate enrichment report (Markdown) or batch update JSON/YAML file
+
+### Phase 3: CLI Artifact Creation (REQUIRED)
+
+```bash
+# Use enrichment to update plan via CLI
+specfact plan update-feature [--bundle <name>] --batch-updates <updates.json> --no-interactive
+# Or use auto-enrich:
+specfact plan review [<bundle-name>] --auto-enrich --no-interactive
+```
+
+**Result**: Final artifacts are CLI-generated with validated enrichments
+
+**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code))
 
 ## Expected Output
 

{specfact_cli-0.13.3 → specfact_cli-0.14.2}/resources/prompts/specfact.04-sdd.md

@@ -58,7 +58,61 @@ specfact plan harden [<bundle-name>] [--sdd <path>] [--output-format <format>]
 
 **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.
+**Rules:**
+
+- Execute CLI first - never create artifacts directly
+- Use `--no-interactive` flag in CI/CD environments
+- Never modify `.specfact/` directly
+- Use CLI output as grounding for validation
+- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only)
+
+## Dual-Stack Workflow (Copilot Mode)
+
+When in copilot mode, follow this three-phase workflow:
+
+### Phase 1: CLI Grounding (REQUIRED)
+
+```bash
+# Execute CLI to get structured output
+specfact plan harden [<bundle-name>] [--sdd <path>] --no-interactive
+```
+
+**Capture**:
+
+- CLI-generated SDD manifest
+- Metadata (hash, coverage metrics)
+- Telemetry (execution time, file counts)
+
+### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only)
+
+**Purpose**: Add semantic understanding to SDD content
+
+**What to do**:
+
+- Read CLI-generated SDD (use file reading tools for display only)
+- Research codebase for additional context
+- Suggest improvements to WHY/WHAT/HOW sections
+
+**What NOT to do**:
+
+- ❌ Create YAML/JSON artifacts directly
+- ❌ Modify CLI artifacts directly (use CLI commands to update)
+- ❌ Bypass CLI validation
+- ❌ Write to `.specfact/` folder directly (always use CLI)
+
+**Output**: Generate enrichment report (Markdown) with suggestions
+
+### Phase 3: CLI Artifact Creation (REQUIRED)
+
+```bash
+# Use enrichment to update plan via CLI, then regenerate SDD
+specfact plan update-idea [--bundle <name>] [options] --no-interactive
+specfact plan harden [<bundle-name>] --no-interactive
+```
+
+**Result**: Final SDD is CLI-generated with validated enrichments
+
+**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code))
 
 ## Expected Output
 

{specfact_cli-0.13.3 → specfact_cli-0.14.2}/resources/prompts/specfact.05-enforce.md

@@ -62,7 +62,61 @@ specfact enforce sdd [<bundle-name>] [--sdd <path>] [--output-format <format>] [
 
 **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.
+**Rules:**
+
+- Execute CLI first - never create artifacts directly
+- Use `--no-interactive` flag in CI/CD environments
+- Never modify `.specfact/` directly
+- Use CLI output as grounding for validation
+- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only)
+
+## Dual-Stack Workflow (Copilot Mode)
+
+When in copilot mode, follow this three-phase workflow:
+
+### Phase 1: CLI Grounding (REQUIRED)
+
+```bash
+# Execute CLI to get structured output
+specfact enforce sdd [<bundle-name>] [--sdd <path>] --no-interactive
+```
+
+**Capture**:
+
+- CLI-generated validation report
+- Deviation counts and severity
+- Coverage metrics vs thresholds
+
+### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only)
+
+**Purpose**: Add semantic understanding to validation results
+
+**What to do**:
+
+- Read CLI-generated validation report (use file reading tools for display only)
+- Research codebase for context on deviations
+- Suggest fixes for validation failures
+
+**What NOT to do**:
+
+- ❌ Create YAML/JSON artifacts directly
+- ❌ Modify CLI artifacts directly (use CLI commands to update)
+- ❌ Bypass CLI validation
+- ❌ Write to `.specfact/` folder directly (always use CLI)
+
+**Output**: Generate fix suggestions report (Markdown)
+
+### Phase 3: CLI Artifact Creation (REQUIRED)
+
+```bash
+# Apply fixes via CLI commands, then re-validate
+specfact plan update-feature [--bundle <name>] [options] --no-interactive
+specfact enforce sdd [<bundle-name>] --no-interactive
+```
+
+**Result**: Final artifacts are CLI-generated with validated fixes
+
+**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code))
 
 ## Expected Output
 

{specfact_cli-0.13.3 → specfact_cli-0.14.2}/resources/prompts/specfact.06-sync.md

@@ -65,7 +65,61 @@ specfact sync bridge --adapter <adapter> --repo <path> [--bidirectional] [--bund
 
 **CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
 
-**Rules:** Execute CLI first, use appropriate flags in CI/CD, never modify `.specfact/` or `.specify/` directly, use CLI output as grounding.
+**Rules:**
+
+- Execute CLI first - never create artifacts directly
+- Use `--no-interactive` flag in CI/CD environments
+- Never modify `.specfact/` or `.specify/` directly
+- Use CLI output as grounding for validation
+- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only)
+
+## Dual-Stack Workflow (Copilot Mode)
+
+When in copilot mode, follow this three-phase workflow:
+
+### Phase 1: CLI Grounding (REQUIRED)
+
+```bash
+# Execute CLI to get structured output
+specfact sync bridge --adapter <adapter> --repo <path> [options] --no-interactive
+```
+
+**Capture**:
+
+- CLI-generated sync results
+- Artifacts synchronized
+- Conflict resolution status
+
+### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only)
+
+**Purpose**: Add semantic understanding to sync results
+
+**What to do**:
+
+- Read CLI-generated sync results (use file reading tools for display only)
+- Research codebase for context on conflicts
+- Suggest resolution strategies
+
+**What NOT to do**:
+
+- ❌ Create YAML/JSON artifacts directly
+- ❌ Modify CLI artifacts directly (use CLI commands to update)
+- ❌ Bypass CLI validation
+- ❌ Write to `.specfact/` or `.specify/` folders directly (always use CLI)
+
+**Output**: Generate conflict resolution suggestions (Markdown)
+
+### Phase 3: CLI Artifact Creation (REQUIRED)
+
+```bash
+# Apply resolutions via CLI commands, then re-sync
+specfact plan update-feature [--bundle <name>] [options] --no-interactive
+specfact sync bridge --adapter <adapter> --repo <path> --no-interactive
+```
+
+**Result**: Final artifacts are CLI-generated with validated resolutions
+
+**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code))
 
 ## Expected Output