specfact-cli 0.11.2__tar.gz → 0.11.4__tar.gz

{specfact_cli-0.11.2 → specfact_cli-0.11.4}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.11.2"
+version = "0.11.4"
 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"
@@ -344,6 +344,7 @@ packages = [
 "resources/templates" = "specfact_cli/resources/templates"
 "resources/schemas" = "specfact_cli/resources/schemas"
 "resources/mappings" = "specfact_cli/resources/mappings"
+# Note: resources/semgrep files are in src/specfact_cli/resources/semgrep/ and are automatically included
 
 [tool.hatch.build.targets.sdist]
 # Only include essential files in source distribution
@@ -520,6 +521,7 @@ testpaths = [
     "tests",
     # "../src" # pythonpath = ["src"] should cover imports from src for tests in /tests
 ]
+# Note: TEST_MODE is set in tests/conftest.py to skip Semgrep in tests
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
@@ -534,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.2 → specfact_cli-0.11.4}/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.2 → specfact_cli-0.11.4}/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.4/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.4/resources/prompts/specfact.03-review.md

@@ -0,0 +1,112 @@
+---
+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
+
+```bash
+specfact plan review [<bundle-name>] [--max-questions <n>] [--category <category>] [--list-questions] [--list-findings] [--answers JSON]
+# Uses active plan if bundle not specified
+```
+
+### Step 3: Present Results
+
+- Display Q&A, sections touched, coverage summary (initial/updated)
+- Note: Clarifications don't affect hash (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
+✓ 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
+/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
+/specfact.03-review --list-questions                   # JSON output
+/specfact.03-review --auto-enrich                     # Auto-enrichment
+```
+
+## Context
+
+{ARGS}

specfact_cli-0.11.4/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.2 → specfact_cli-0.11.4}/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

{specfact_cli-0.11.2 → specfact_cli-0.11.4}/resources/prompts/specfact.06-sync.md

@@ -14,20 +14,11 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Purpose
 
-Synchronize artifacts from external tools (e.g., Spec-Kit, Linear, Jira) with SpecFact project bundles using configurable bridge mappings. Supports bidirectional sync for team collaboration.
+Synchronize artifacts from external tools (Spec-Kit, Linear, Jira) with SpecFact project bundles using bridge mappings. Supports bidirectional sync.
 
-**When to use:**
+**When to use:** Syncing with Spec-Kit, integrating external tools, maintaining consistency.
 
-- Syncing with Spec-Kit projects
-- Integrating with external planning tools
-- Maintaining consistency across tool ecosystems
-
-**Quick Example:**
-
-```bash
-/specfact.06-sync --adapter speckit --repo . --bidirectional
-/specfact.06-sync --adapter speckit --bundle legacy-api --watch
-```
+**Quick:** `/specfact.06-sync --adapter speckit --repo . --bidirectional` or `/specfact.06-sync --bundle legacy-api --watch`
 
 ## Parameters
 
@@ -59,14 +50,8 @@ Synchronize artifacts from external tools (e.g., Spec-Kit, Linear, Jira) with Sp
 ### Step 2: Execute CLI
 
 ```bash
-# Bidirectional sync
-specfact sync bridge --adapter <adapter> --repo <path> --bidirectional [--bundle <name>] [--overwrite] [--watch]
-
-# One-way sync (Spec-Kit → SpecFact)
-specfact sync bridge --adapter speckit --repo <path> [--bundle <name>]
-
-# Watch mode
-specfact sync bridge --adapter speckit --repo <path> --watch --interval 5
+specfact sync bridge --adapter <adapter> --repo <path> [--bidirectional] [--bundle <name>] [--overwrite] [--watch] [--interval <seconds>]
+# --bundle defaults to active plan if not specified
 ```
 
 ### Step 3: Present Results
@@ -80,13 +65,7 @@ specfact sync bridge --adapter speckit --repo <path> --watch --interval 5
 
 **CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
 
-**Rules:**
-
-1. **ALWAYS execute CLI first**: Run `specfact sync bridge` before any sync operation
-2. **ALWAYS use non-interactive mode for CI/CD**: Use appropriate flags in Copilot environments
-3. **NEVER modify .specfact or .specify folders directly**: All operations must go through CLI
-4. **NEVER create YAML/JSON directly**: All sync operations must be CLI-generated
-5. **Use CLI output as grounding**: Parse CLI output, don't regenerate it
+**Rules:** Execute CLI first, use appropriate flags in CI/CD, never modify `.specfact/` or `.specify/` directly, use CLI output as grounding.
 
 ## Expected Output
 
@@ -115,20 +94,10 @@ Supported adapters: speckit, generic-markdown
 ## Common Patterns
 
 ```bash
-# Bidirectional sync with Spec-Kit
 /specfact.06-sync --adapter speckit --repo . --bidirectional
-
-# One-way sync (Spec-Kit → SpecFact)
 /specfact.06-sync --adapter speckit --repo . --bundle legacy-api
-
-# Watch mode for continuous sync
 /specfact.06-sync --adapter speckit --repo . --watch --interval 5
-
-# Sync with overwrite
-/specfact.06-sync --adapter speckit --repo . --bidirectional --overwrite
-
-# Auto-detect adapter
-/specfact.06-sync --repo . --bidirectional
+/specfact.06-sync --repo . --bidirectional  # Auto-detect adapter
 ```
 
 ## Context