specfact-cli 0.9.0__tar.gz → 0.9.2__tar.gz

{specfact_cli-0.9.0 → specfact_cli-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.9.0
+Version: 0.9.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
@@ -353,13 +353,13 @@ pip install specfact-cli
 
 ```bash
 # Modernizing legacy code? (Recommended)
-specfact import from-code --repo . --name my-project
+specfact import from-code my-project --repo .
 
 # Starting a new project?
-specfact plan init --interactive
+specfact plan init my-project --interactive
 
-# Using GitHub Spec-Kit?
-specfact import from-spec-kit --repo ./my-project --dry-run
+# Using GitHub Spec-Kit or other tools?
+specfact import from-bridge --repo ./my-project --adapter speckit --write
 ```
 
 That's it! 🎉

{specfact_cli-0.9.0 → specfact_cli-0.9.2}/README.md

@@ -87,13 +87,13 @@ pip install specfact-cli
 
 ```bash
 # Modernizing legacy code? (Recommended)
-specfact import from-code --repo . --name my-project
+specfact import from-code my-project --repo .
 
 # Starting a new project?
-specfact plan init --interactive
+specfact plan init my-project --interactive
 
-# Using GitHub Spec-Kit?
-specfact import from-spec-kit --repo ./my-project --dry-run
+# Using GitHub Spec-Kit or other tools?
+specfact import from-bridge --repo ./my-project --adapter speckit --write
 ```
 
 That's it! 🎉

{specfact_cli-0.9.0 → specfact_cli-0.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.9.0"
+version = "0.9.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.9.0 → specfact_cli-0.9.2}/resources/prompts/specfact-enforce.md

@@ -53,7 +53,12 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## 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).
+Configure quality gates and enforcement modes for contract validation. This command has two subcommands:
+
+1. **`enforce stage`** - Sets the enforcement preset that determines how contract violations are handled (minimal, balanced, strict)
+2. **`enforce sdd`** - Validates SDD manifest against project bundle and contracts (requires bundle name)
+
+This prompt focuses on **`enforce stage`**. For SDD validation, see the `enforce sdd` command which requires a project bundle name.
 
 ## Operating Constraints
 
@@ -61,6 +66,8 @@ Configure quality gates and enforcement modes for contract validation. This comm
 
 **Command**: `specfact enforce stage`
 
+**Note**: This prompt covers `enforce stage` only. The `enforce sdd` subcommand requires a project bundle name (e.g., `specfact enforce sdd legacy-api`) and validates SDD manifests against project bundles.
+
 **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
@@ -141,7 +148,8 @@ specfact enforce stage --preset strict
 | LOW      | Log    |
 
 **Next Steps**:
-- Run validation: `/specfact-cli/specfact-repro`
+- Run validation: `specfact repro`
+- Validate SDD: `specfact enforce sdd <bundle-name>` (requires project bundle)
 - Review configuration: Check `.specfact/config/enforcement.yaml`
 ```
 

{specfact_cli-0.9.0 → specfact_cli-0.9.2}/resources/prompts/specfact-import-from-code.md

@@ -58,18 +58,18 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 **For updating features** (after enrichment):
 
-- `specfact plan update-feature --key <key> --title <title> --outcomes <outcomes> --acceptance <acceptance> --constraints <constraints> --confidence <confidence> --draft <true/false> --plan <path>`
+- `specfact plan update-feature --bundle <bundle-name> --key <key> --title <title> --outcomes <outcomes> --acceptance <acceptance> --constraints <constraints> --confidence <confidence> --draft/--no-draft`
   - Updates existing feature metadata (title, outcomes, acceptance criteria, constraints, confidence, draft status)
   - Works in CI/CD, Copilot, and interactive modes
-  - Example: `specfact plan update-feature --key FEATURE-001 --title "New Title" --outcomes "Outcome 1, Outcome 2"`
+  - Example: `specfact plan update-feature --bundle legacy-api --key FEATURE-001 --title "New Title" --outcomes "Outcome 1, Outcome 2"`
 
 **For adding features**:
 
-- `specfact plan add-feature --key <key> --title <title> --outcomes <outcomes> --acceptance <acceptance> --plan <path>`
+- `specfact plan add-feature --bundle <bundle-name> --key <key> --title <title> --outcomes <outcomes> --acceptance <acceptance>`
 
 **For adding stories**:
 
-- `specfact plan add-story --feature <feature-key> --key <story-key> --title <title> --acceptance <acceptance> --story-points <points> --value-points <points> --plan <path>`
+- `specfact plan add-story --bundle <bundle-name> --feature <feature-key> --key <story-key> --title <title> --acceptance <acceptance> --story-points <points> --value-points <points>`
 
 **❌ FORBIDDEN**: Direct Python code manipulation like:
 
@@ -85,7 +85,7 @@ generator.generate(plan_bundle, plan_path)  # Bypassing CLI
 
 ```bash
 # ✅ ALWAYS DO THIS:
-specfact plan update-feature --key FEATURE-001 --title "New Title" --plan <path>
+specfact plan update-feature --bundle legacy-api --key FEATURE-001 --title "New Title"
 ```
 
 ## ⏸️ Wait States: User Input Required
@@ -197,8 +197,8 @@ specfact import from-code --repo <path> --name <name> --entry-point <subdirector
 **Apply enrichments via CLI using the `--enrichment` flag**:
 
 ```bash
-# Apply enrichment report to refine the auto-detected plan bundle
-specfact import from-code --repo <path> --name <name> --enrichment <enrichment-report-path>
+# Apply enrichment report to refine the auto-detected project bundle
+specfact import from-code <bundle-name> --repo <path> --enrichment <enrichment-report-path>
 ```
 
 **The `--enrichment` flag**:
@@ -250,9 +250,8 @@ specfact import from-code --repo <path> --name <name> --enrichment <enrichment-r
 Extract arguments from user input:
 
 - `--repo PATH` - Repository path (default: current directory)
-- `--name NAME` - Custom plan name (will be sanitized for filesystem, optional, default: "auto-derived")
+- `BUNDLE_NAME` - Project bundle name (required positional argument, e.g., `legacy-api`, `auth-module`)
 - `--confidence FLOAT` - Minimum confidence score (0.0-1.0, default: 0.5)
-- `--out PATH` - Output plan bundle path (optional, default: `.specfact/plans/<name>-<timestamp>.bundle.<format>`)
 - `--report PATH` - Analysis report path (optional, default: `.specfact/reports/brownfield/analysis-<timestamp>.md`)
 - `--shadow-only` - Observe mode without enforcing (optional)
 - `--key-format {classname|sequential}` - Feature key format (default: `classname`)
@@ -262,13 +261,13 @@ Extract arguments from user input:
   - Incremental modernization: Modernize one part of the codebase at a time
   - Example: `--entry-point projects/api-service` analyzes only `projects/api-service/` and its subdirectories
 
-**Important**: If `--name` is not provided, **ask the user interactively** for a meaningful plan name and **WAIT for their response**. The name will be automatically sanitized (lowercased, spaces/special chars removed) for filesystem persistence.
+**Important**: Bundle name is **required**. If not provided, **ask the user interactively** for a bundle name and **WAIT for their response**. Use kebab-case (e.g., `legacy-api`, `auth-module`).
 
-**WAIT STATE**: If `--name` is missing, you MUST:
+**WAIT STATE**: If bundle name is missing, you MUST:
 
-1. Ask: "What name would you like to use for this plan? (e.g., 'API Client v2', 'User Authentication', 'Payment Processing')"
+1. Ask: "What bundle name would you like to use? (e.g., 'legacy-api', 'auth-module', 'payment-service')"
 2. **STOP and WAIT** for user response
-3. **DO NOT continue** until user provides a name
+3. **DO NOT continue** until user provides a bundle name
 
 For single quotes in args like "I'm Groot", use escape syntax: e.g `'I'\''m Groot'` (or double-quote if possible: `"I'm Groot"`).
 
@@ -278,17 +277,17 @@ For single quotes in args like "I'm Groot", use escape syntax: e.g `'I'\''m Groo
 
 ```bash
 # Full repository analysis
-specfact import from-code --repo <repo_path> --name <plan_name> --confidence <confidence>
+specfact import from-code <bundle-name> --repo <repo_path> --confidence <confidence>
 
 # Partial repository analysis (analyze only specific subdirectory)
-specfact import from-code --repo <repo_path> --name <plan_name> --entry-point <subdirectory> --confidence <confidence>
+specfact import from-code <bundle-name> --repo <repo_path> --entry-point <subdirectory> --confidence <confidence>
 ```
 
 **Note**: Mode is auto-detected by the CLI. No need to specify `--mode` flag.
 
 **Capture CLI output**:
 
-- Plan bundle path: `.specfact/plans/<name>-<timestamp>.bundle.<format>`
+- Project bundle directory: `.specfact/projects/<bundle-name>/`
 - Analysis report path: `.specfact/reports/brownfield/analysis-<timestamp>.md`
 - Metadata: feature counts, story counts, average confidence, execution time
 - **Deduplication summary**: "✓ Removed N duplicate features from plan bundle" (if duplicates were found during import)
@@ -340,12 +339,8 @@ The CLI automatically deduplicates features during import using normalized key m
    - Semantic insights and recommendations
 
 4. **Save enrichment report** to the proper location:
-   - Extract the plan bundle path from CLI output (e.g., `.specfact/plans/specfact-cli.2025-11-17T09-26-47.bundle.<format>`)
-   - Derive enrichment report path by:
-     - Taking the plan bundle filename (e.g., `specfact-cli.2025-11-17T09-26-47.bundle.<format>`)
-     - Replacing `.bundle.<format>` with `.enrichment.md` (e.g., `specfact-cli.2025-11-17T09-26-47.enrichment.md`)
-     - Placing it in `.specfact/reports/enrichment/` directory
-   - Full path example: `.specfact/reports/enrichment/specfact-cli.2025-11-17T09-26-47.enrichment.md`
+   - Use bundle name from CLI output (e.g., `legacy-api`)
+   - Derive enrichment report path: `.specfact/reports/enrichment/<bundle-name>-<timestamp>.enrichment.md`
    - **Ensure the directory exists**: Create `.specfact/reports/enrichment/` if it doesn't exist
 
 **What NOT to do**:
@@ -360,29 +355,24 @@ The CLI automatically deduplicates features during import using normalized key m
 
 **If enrichment was generated**:
 
-1. **Save enrichment report** to the enrichment reports directory with a name that matches the plan bundle:
+1. **Save enrichment report** to the enrichment reports directory:
    - Location: `.specfact/reports/enrichment/`
-   - Naming: Use the same name and timestamp as the plan bundle, replacing `.bundle.<format>` with `.enrichment.md`
-   - Example: If plan bundle is `specfact-cli.2025-11-17T09-26-47.bundle.<format>`, save enrichment as `specfact-cli.2025-11-17T09-26-47.enrichment.md`
-   - Full path: `.specfact/reports/enrichment/specfact-cli.2025-11-17T09-26-47.enrichment.md`
+   - Naming: `<bundle-name>-<timestamp>.enrichment.md`
+   - Example: `.specfact/reports/enrichment/legacy-api-2025-11-17T09-26-47.enrichment.md`
 
 2. **Execute CLI with `--enrichment` flag**:
 
    ```bash
-   specfact import from-code --repo <repo_path> --name <plan_name> --enrichment <enrichment-report-path>
+   specfact import from-code <bundle-name> --repo <repo_path> --enrichment <enrichment-report-path>
    ```
 
 3. **The CLI will**:
-   - Load the original plan bundle (if it exists, derived from enrichment report path)
+   - Load the original project bundle from `.specfact/projects/<bundle-name>/`
    - Parse the enrichment report
-   - Apply missing features to the plan bundle
+   - Apply missing features to the project bundle
    - Adjust confidence scores
    - Add business context
-   - Validate and write the enriched plan bundle as a **new file** with clear naming:
-     - Format: `<name>.<original-timestamp>.enriched.<enrichment-timestamp>.bundle.<format>`
-     - Example: `specfact-cli.2025-11-17T09-26-47.enriched.2025-11-17T11-15-29.bundle.<format>`
-     - The original plan bundle remains unchanged
-     - The enriched plan is stored as a separate file for comparison and versioning
+   - Validate and save the enriched project bundle (updates existing bundle)
 
 **If no enrichment**:
 
@@ -410,11 +400,9 @@ If `--report` is provided, generate a Markdown import report:
 
 ### 6. Present Results
 
-**Present the CLI-generated plan bundle** to the user:
+**Present the CLI-generated project bundle** to the user:
 
-- **Plan bundle location**: Show where the CLI wrote the YAML file
-- **Original plan** (if enrichment was applied): Show the original plan bundle path
-- **Enriched plan** (if enrichment was applied): Show the enriched plan bundle path with clear naming
+- **Project bundle location**: `.specfact/projects/<bundle-name>/`
 - **Feature summary**: List features from CLI output with confidence scores
 - **Story summary**: List stories from CLI output per feature
 - **CLI metadata**: Execution time, file counts, validation results
@@ -425,8 +413,7 @@ If `--report` is provided, generate a Markdown import report:
 ```markdown
 ✓ Import complete!
 
-Original plan: specfact-cli.2025-11-17T09-26-47.bundle.<format>
-Enriched plan: specfact-cli.2025-11-17T09-26-47.enriched.2025-11-17T11-15-29.bundle.<format>
+Project bundle: .specfact/projects/legacy-api/
 
 CLI Analysis Results:
 - Features identified: 19
@@ -604,7 +591,7 @@ When comparing imported plans with main plans:
 
 To compare plans, normalize feature keys by removing prefixes and underscores, then match by normalized key.
 
-**Important**: This is a **one-way import** - it imports from code into SpecFact format. It does NOT perform consistency checking on Spec-Kit artifacts. For Spec-Kit artifact consistency checking, use Spec-Kit's `/speckit.analyze` command instead.
+**Important**: This is a **one-way import** - it imports from code into SpecFact modular project bundle format. For external tool integration (Spec-Kit, Linear, Jira), use `specfact import from-bridge --adapter <adapter>` instead.
 
 ## Constitution Bootstrap (Optional)
 

{specfact_cli-0.9.0 → specfact_cli-0.9.2}/resources/prompts/specfact-plan-add-feature.md

@@ -67,13 +67,13 @@ Add a new feature to an existing plan bundle. The feature will be added with the
 
 The `specfact plan add-feature` command:
 
-1. **Loads** the existing plan bundle (default: `.specfact/plans/main.bundle.<format>` or active plan)
-2. **Validates** the plan bundle structure
+1. **Loads** the existing project bundle from `.specfact/projects/<bundle-name>/`
+2. **Validates** the project bundle structure
 3. **Checks** if the feature key already exists (prevents duplicates)
 4. **Creates** a new feature with specified metadata
-5. **Adds** the feature to the plan bundle
-6. **Validates** the updated plan bundle
-7. **Saves** the updated plan bundle
+5. **Adds** the feature to the project bundle (saves to `features/FEATURE-XXX.yaml`)
+6. **Validates** the updated project bundle
+7. **Saves** the updated project bundle
 
 ## Execution Steps
 
@@ -81,11 +81,11 @@ The `specfact plan add-feature` command:
 
 **Parse user input** to extract:
 
+- `--bundle <bundle-name>` - Project bundle name (required, e.g., `legacy-api`)
 - Feature key (required, e.g., `FEATURE-001`)
 - Feature title (required)
 - Outcomes (optional, comma-separated)
 - Acceptance criteria (optional, comma-separated)
-- Plan bundle path (optional, defaults to active plan or `.specfact/plans/main.bundle.<format>`)
 
 **WAIT STATE**: If required arguments are missing, ask the user:
 
@@ -100,17 +100,17 @@ Please provide these values:
 
 ### 2. Check Plan Bundle Existence
 
-**Execute CLI** to check if plan exists:
+**WAIT STATE**: If `--bundle` is missing, ask user for bundle name and **WAIT**:
 
-```bash
-# Check if default plan exists
-specfact plan select
+```text
+"Which project bundle should I use? (e.g., 'legacy-api', 'auth-module')
+[WAIT FOR USER RESPONSE - DO NOT CONTINUE]"
 ```
 
-**If plan doesn't exist**:
+**If bundle doesn't exist**:
 
-- Report error: "Default plan not found. Create one with: `specfact plan init --interactive`"
-- **WAIT STATE**: Ask user if they want to create a new plan or specify a different path
+- Report error: "Project bundle not found. Create one with: `specfact plan init <bundle-name>`"
+- **WAIT STATE**: Ask user if they want to create a new bundle or specify a different bundle name
 
 ### 3. Execute Add Feature Command
 
@@ -118,15 +118,15 @@ specfact plan select
 
 ```bash
 # Basic usage
-specfact plan add-feature --key FEATURE-001 --title "Feature Title" --plan <plan_path>
+specfact plan add-feature --bundle <bundle-name> --key FEATURE-001 --title "Feature Title"
 
 # With outcomes and acceptance
 specfact plan add-feature \
+  --bundle <bundle-name> \
   --key FEATURE-001 \
   --title "Feature Title" \
   --outcomes "Outcome 1, Outcome 2" \
-  --acceptance "Criterion 1, Criterion 2" \
-  --plan <plan_path>
+  --acceptance "Criterion 1, Criterion 2"
 ```
 
 **Capture from CLI**:
@@ -141,7 +141,7 @@ specfact plan add-feature \
 **Common errors**:
 
 - **Feature key already exists**: Report error and suggest using `specfact plan update-feature` instead
-- **Plan bundle not found**: Report error and suggest creating plan with `specfact plan init`
+- **Project bundle not found**: Report error and suggest creating bundle with `specfact plan init <bundle-name>`
 - **Invalid plan structure**: Report validation error
 
 ### 5. Report Completion
@@ -155,7 +155,7 @@ specfact plan add-feature \
 **Title**: Feature Title
 **Outcomes**: Outcome 1, Outcome 2
 **Acceptance**: Criterion 1, Criterion 2
-**Plan Bundle**: `.specfact/plans/main.bundle.<format>`
+**Project Bundle**: `.specfact/projects/<bundle-name>/`
 
 **Next Steps**:
 - Add stories to this feature: `/specfact-cli/specfact-plan-add-story`

{specfact_cli-0.9.0 → specfact_cli-0.9.2}/resources/prompts/specfact-plan-add-story.md

@@ -133,7 +133,7 @@ specfact plan add-story \
   --feature FEATURE-001 \
   --key STORY-001 \
   --title "Story Title" \
-  --plan <plan_path>
+  --bundle <bundle-name>
 
 # With acceptance criteria and points
 specfact plan add-story \
@@ -143,7 +143,7 @@ specfact plan add-story \
   --acceptance "Criterion 1, Criterion 2" \
   --story-points 5 \
   --value-points 3 \
-  --plan <plan_path>
+  --bundle <bundle-name>
 ```
 
 **Capture from CLI**:

{specfact_cli-0.9.0 → specfact_cli-0.9.2}/resources/prompts/specfact-plan-compare.md

@@ -18,7 +18,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 ### Rules
 
 1. **ALWAYS execute CLI first**: Run `specfact plan compare` before any comparison - execute the CLI command before any other operations
-2. **ALWAYS use non-interactive mode for CI/CD**: When executing CLI commands, use `--non-interactive` flag to avoid interactive prompts that can cause timeouts in Copilot environments
+2. **ALWAYS use non-interactive mode for CI/CD**: When executing CLI commands, use `--no-interactive` flag to avoid interactive prompts that can cause timeouts in Copilot environments
 3. **ALWAYS use tools for read/write**: Use file reading tools (e.g., `read_file`) to read artifacts for display purposes only. Use CLI commands for all write operations. Never use direct file manipulation.
 4. **NEVER modify .specfact folder directly**: Do NOT create, modify, or delete any files in `.specfact/` folder directly. All operations must go through the CLI.
 5. **NEVER write code**: Do not implement comparison logic - the CLI handles this
@@ -52,9 +52,9 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Goal
 
-Compare a manual plan bundle with an auto-derived plan bundle to detect deviations, mismatches, and missing features. This command helps identify gaps between planned features and actual implementation, ensuring alignment between specification and code.
+Compare two project bundles (or legacy plan bundles) to detect deviations, mismatches, and missing features. This command helps identify gaps between planned features and actual implementation, ensuring alignment between specification and code.
 
-**Note**: This is a **read-only comparison** operation - it generates comparison reports but does not modify plan bundles.
+**Note**: This is a **read-only comparison** operation - it generates comparison reports but does not modify bundles. Works with both modular project bundles (`.specfact/projects/<bundle-name>/`) and legacy monolithic bundles (`.specfact/plans/*.bundle.<format>`).
 
 ## Action Required
 
@@ -75,10 +75,11 @@ Compare a manual plan bundle with an auto-derived plan bundle to detect deviatio
    - Parse the CLI table output to get plan names for the specified numbers
    - Extract the full plan file names from the table
 
-   - **For CI/CD/non-interactive use**: Use `--non-interactive` with filters:
-   ```
-   specfact plan select --non-interactive --current
-   specfact plan select --non-interactive --last 1
+   - **For CI/CD/non-interactive use**: Use `--no-interactive` with filters:
+
+   ```bash
+   specfact plan select --no-interactive --current
+   specfact plan select --no-interactive --last 1
    ```
 
 2. **Get full plan paths using CLI**:
@@ -87,13 +88,14 @@ Compare a manual plan bundle with an auto-derived plan bundle to detect deviatio
    specfact plan select <plan_number>
    ```
 
-   - This will output the full plan name/path
-   - Use this to construct the full path: `.specfact/plans/<plan_name>`
+   - This will output the full bundle name/path
+   - Use this to construct the full path: `.specfact/projects/<bundle-name>/` (for project bundles) or `.specfact/plans/<plan_name>` (for legacy bundles)
 
-   - **For CI/CD/non-interactive use**: Use `--non-interactive` with filters:
-   ```
-   specfact plan select --non-interactive --current
-   specfact plan select --non-interactive --last 1
+   - **For CI/CD/non-interactive use**: Use `--no-interactive` with filters:
+
+   ```bash
+   specfact plan select --no-interactive --current
+   specfact plan select --no-interactive --last 1
    ```
 
 **If user input contains plan names** (e.g., "main.bundle.<format> vs auto-derived.bundle.<format>"):
@@ -105,10 +107,10 @@ Compare a manual plan bundle with an auto-derived plan bundle to detect deviatio
 
 **If arguments missing**: Ask user interactively for each missing argument and **WAIT for their response**:
 
-1. **Manual plan path**: "Which manual plan to compare? (Enter plan number, plan name, or path. Default: .specfact/plans/main.bundle.<format>)"
+1. **Manual bundle path**: "Which manual bundle to compare? (Enter bundle name, plan number, or path. Default: active bundle or .specfact/projects/main/)"
    - **[WAIT FOR USER RESPONSE - DO NOT CONTINUE]**
 
-2. **Auto plan path**: "Which auto-derived plan to compare? (Enter plan number, plan name, or path. Default: latest in .specfact/plans/)"
+2. **Auto bundle path**: "Which auto-derived bundle to compare? (Enter bundle name, plan number, or path. Default: latest in .specfact/projects/)"
    - **[WAIT FOR USER RESPONSE - DO NOT CONTINUE]**
 
 3. **Output format**: "Output format? (1) Markdown, (2) JSON, (3) YAML (default: markdown)"
@@ -133,7 +135,7 @@ Compare a manual plan bundle with an auto-derived plan bundle to detect deviatio
 ## Command
 
 ```bash
-specfact plan compare [--manual PATH] [--auto PATH] [--format {markdown|json|yaml}] [--out PATH]
+specfact plan compare [--manual PATH] [--auto PATH] [--output-format {markdown|json|yaml}] [--out PATH]
 ```
 
 **Note**: Mode is auto-detected by the CLI. No need to specify `--mode` flag.
@@ -144,11 +146,16 @@ specfact plan compare [--manual PATH] [--auto PATH] [--format {markdown|json|yam
 
 **Arguments:**
 
-- `--manual PATH` - Manual plan bundle path (default: `.specfact/plans/main.bundle.<format>`) - **ASK USER if default not found**
-- `--auto PATH` - Auto-derived plan bundle path (default: latest in `.specfact/reports/brownfield/`) - **ASK USER if default not found**
-- `--format {markdown|json|yaml}` - Output format (default: `markdown`) - **ASK USER if not specified**
+- `--manual PATH` - Manual bundle path (project bundle directory or legacy plan file). Default: active bundle or `.specfact/projects/main/` - **ASK USER if default not found**
+- `--auto PATH` - Auto-derived bundle path (project bundle directory or legacy plan file). Default: latest in `.specfact/projects/` - **ASK USER if default not found**
+- `--output-format {markdown|json|yaml}` - Output format (default: `markdown`) - **ASK USER if not specified**
 - `--out PATH` - Output file path (optional, default: auto-generated in `.specfact/reports/comparison/`)
 
+**Note**: Paths can be:
+
+- Project bundle directories: `.specfact/projects/<bundle-name>/` (modular format)
+- Legacy plan files: `.specfact/plans/*.bundle.<format>` (monolithic format, for backward compatibility)
+
 **What it does:**
 
 1. Loads and validates both plan bundles (manual and auto-derived)
@@ -181,13 +188,14 @@ specfact plan compare [--manual PATH] [--auto PATH] [--format {markdown|json|yam
      specfact plan select <plan_number>
      ```
 
-     - Parse the CLI output to get the full plan name
-     - Construct full path: `.specfact/plans/<plan_name>`
+     - Parse the CLI output to get the full bundle name
+     - Construct full path: `.specfact/projects/<bundle-name>/` (for project bundles) or `.specfact/plans/<plan_name>` (for legacy bundles)
 
-     - **For CI/CD/non-interactive use**: Use `--non-interactive` with filters:
-     ```
-     specfact plan select --non-interactive --current
-     specfact plan select --non-interactive --last 1
+     - **For CI/CD/non-interactive use**: Use `--no-interactive` with filters:
+
+     ```bash
+     specfact plan select --no-interactive --current
+     specfact plan select --no-interactive --last 1
      ```
 
 - **If user input contains plan names** (e.g., "main.bundle.<format> vs auto-derived.bundle.<format>"):
@@ -198,14 +206,14 @@ specfact plan compare [--manual PATH] [--auto PATH] [--format {markdown|json|yam
 
 **Step 2**: Resolve manual plan path.
 
-- **If plan number/name provided**: Use CLI to resolve (see Step 1)
-- **If missing**: Check if default path (`.specfact/plans/main.bundle.<format>`) exists using CLI
-  - **Verify using CLI**: Attempt to use the path with `specfact plan compare` - if it fails, the file doesn't exist
+- **If bundle name/plan number provided**: Use CLI to resolve (see Step 1)
+- **If missing**: Check if default path (`.specfact/projects/main/` or `.specfact/plans/main.bundle.<format>`) exists using CLI
+  - **Verify using CLI**: Attempt to use the path with `specfact plan compare` - if it fails, the bundle doesn't exist
   - **If not exists**: Ask user and **WAIT**:
 
     ```text
-    "Manual plan not found at default location. Enter plan number, plan name, or path to manual plan bundle, 
-    or create one with `specfact plan init --interactive`?
+    "Manual bundle not found at default location. Enter bundle name, plan number, or path to manual bundle, 
+    or create one with `specfact plan init <bundle-name>`?
     [WAIT FOR USER RESPONSE - DO NOT CONTINUE]"
     ```
 
@@ -220,7 +228,7 @@ specfact plan compare [--manual PATH] [--auto PATH] [--format {markdown|json|yam
     ```
 
   - **Parse CLI output** to find latest auto-derived plan (by modification date)
-  - **For CI/CD/non-interactive**: Use `specfact plan select --non-interactive --last 1` to get most recent plan
+  - **For CI/CD/non-interactive**: Use `specfact plan select --no-interactive --last 1` to get most recent plan
   - **If found**: Ask user and **WAIT**:
 
     ```text
@@ -231,12 +239,12 @@ specfact plan compare [--manual PATH] [--auto PATH] [--format {markdown|json|yam
   - **If not found**: Ask user and **WAIT**:
 
     ```text
-    "No auto-derived plans found. Enter plan number, plan name, or path to auto-derived plan bundle, 
-    or generate one with `specfact import from-code --repo . --name my-project`?
+    "No auto-derived bundles found. Enter bundle name, plan number, or path to auto-derived bundle, 
+    or generate one with `specfact import from-code <bundle-name> --repo .`?
     [WAIT FOR USER RESPONSE - DO NOT CONTINUE]"
     ```
 
-**Step 3**: Check if `--format` is specified.
+**Step 3**: Check if `--output-format` is specified.
 
 - **If missing**: Ask user and **WAIT**:
 
@@ -278,15 +286,16 @@ specfact plan compare [--manual PATH] [--auto PATH] [--format {markdown|json|yam
 **⚠️ CRITICAL**: Use the resolved file paths (not plan numbers) in the CLI command:
 
 ```bash
-specfact plan compare --manual <MANUAL_PATH> --auto <AUTO_PATH> --format <FORMAT> --out <OUT_PATH>
+specfact plan compare --manual <MANUAL_PATH> --auto <AUTO_PATH> --output-format <FORMAT> --out <OUT_PATH>
 ```
 
-**Example**: If user said "19 vs 20", and CLI resolved them to:
+**Example**: If user said "legacy-api vs modernized-api", execute:
 
-- Plan 19: `specfact-import-test-v2.2025-11-17T13-53-31.bundle.<format>`
-- Plan 20: `specfact-import-test-v2.2025-11-17T13-53-31.enriched.2025-11-17T13-55-40.bundle.<format>`
+```bash
+specfact plan compare --manual .specfact/projects/legacy-api/ --auto .specfact/projects/modernized-api/
+```
 
-Then execute:
+**Example**: If user said "19 vs 20" (legacy plan numbers), and CLI resolved them to legacy plan files:
 
 ```bash
 specfact plan compare --manual .specfact/plans/specfact-import-test-v2.2025-11-17T13-53-31.bundle.<format> --auto .specfact/plans/specfact-import-test-v2.2025-11-17T13-53-31.enriched.2025-11-17T13-55-40.bundle.<format>
@@ -306,14 +315,14 @@ specfact plan compare --manual .specfact/plans/specfact-import-test-v2.2025-11-1
 ```bash
 SpecFact CLI - Plan Comparator
 
-Manual Plan: .specfact/plans/main.bundle.<format>
-Auto Plan: .specfact/reports/brownfield/auto-derived-2025-11-02T12-00-00.bundle.<format>
+Manual Bundle: .specfact/projects/main/
+Auto Bundle: .specfact/projects/legacy-api/
 Total Deviations: 15
 
 Comparison Results
 
-Manual Plan: .specfact/plans/main.bundle.<format>
-Auto Plan: .specfact/reports/brownfield/auto-derived-2025-11-02T12-00-00.bundle.<format>
+Manual Bundle: .specfact/projects/main/
+Auto Bundle: .specfact/projects/legacy-api/
 Total Deviations: 15
 
 Deviation Summary:
@@ -358,7 +367,7 @@ Fix the blocking deviations or adjust enforcement config
 **ALWAYS execute the specfact CLI** to perform the comparison:
 
 ```bash
-specfact plan compare --manual <manual_path> --auto <auto_path> --format <format> --out <output_path>
+specfact plan compare --manual <manual_path> --auto <auto_path> --output-format <format> --out <output_path>
 ```
 
 **The CLI performs**: