feat: enhance target user extraction and remove GWT format references (v0.11.3)

CHANGELOG.md

@@ -9,6 +9,39 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.11.3] - 2025-12-01
+
+### Changed (0.11.3)
+
+- **Enhanced Target User Extraction in Plan Review**
+  - Refactored `_extract_target_users()` to prioritize reliable metadata sources over codebase scanning
+  - **Priority order** (most reliable first):
+    1. `pyproject.toml` classifiers (e.g., "Intended Audience :: Developers")
+    2. `README.md` patterns ("Perfect for:", "Target users:", etc.)
+    3. Story titles with "As a..." patterns
+    4. Codebase user models (optional fallback only if <2 suggestions found)
+  - Removed keyword extraction from `pyproject.toml` (keywords are technical terms, not personas)
+  - Simplified excluded terms list (reduced from 60+ to 14 terms)
+  - Improved README.md extraction to skip use cases (e.g., "data pipelines", "devops scripts")
+  - Updated question text from "Suggested from codebase" to "Suggested" (reflects multiple sources)
+
+- **Removed GWT Format References**
+  - Removed outdated "Given/When/Then format" question from completion signals scanning
+  - Updated vague acceptance criteria question to: "Should these be more specific? Note: Detailed test examples should be in OpenAPI contract files, not acceptance criteria."
+  - Removed "given", "when", "then" from testability keywords check
+  - Clarifies that acceptance criteria are simple text descriptions, not OpenAPI format
+  - Aligns with Phase 4/5 design where detailed examples are in OpenAPI contracts
+
+### Fixed (0.11.3)
+
+- **Target User Extraction Accuracy**
+  - Fixed false positives from codebase scanning (e.g., "Detecting", "Data Pipelines", "Async", "Beartype", "Brownfield")
+  - Now only extracts actual user personas from reliable metadata sources
+  - Codebase extraction only runs as fallback when metadata provides <2 suggestions
+  - Improved filtering to exclude technical terms and use cases
+
+---
+
 ## [0.11.2] - 2025-11-30
 
 ### Fixed (0.11.2)

docs/reference/architecture.md

@@ -44,6 +44,9 @@ SpecFact CLI supports two operational modes for different use cases:
 - No AI copilot dependency
 - Direct command execution
 - Structured JSON/Markdown output
+- **Enhanced Analysis**: AST + Semgrep hybrid pattern detection (API endpoints, models, CRUD, code quality)
+- **Optimized Bundle Size**: 81% reduction (18MB → 3.4MB, 5.3x smaller) via test pattern extraction to OpenAPI contracts
+- **Interruptible**: All parallel operations support Ctrl+C for immediate cancellation
 
 **Usage:**
 
@@ -484,13 +487,57 @@ src/specfact_cli/
 │   ├── console.py       # Rich console output
 │   ├── git.py           # Git operations
 │   └── yaml_utils.py    # YAML helpers
+├── analyzers/          # Code analysis engines
+│   ├── code_analyzer.py # AST+Semgrep hybrid analysis
+│   ├── graph_analyzer.py # Dependency graph analysis
+│   └── relationship_mapper.py # Relationship extraction
 └── common/              # Shared utilities
     ├── logger_setup.py  # Logging infrastructure
     ├── logging_utils.py # Logging helpers
     ├── text_utils.py    # Text utilities
     └── utils.py         # File/JSON utilities
 ```
 
+## Analysis Components
+
+### AST+Semgrep Hybrid Analysis
+
+The `CodeAnalyzer` uses a hybrid approach combining AST parsing with Semgrep pattern detection:
+
+**AST Analysis** (Core):
+
+- Structural code analysis (classes, methods, imports)
+- Type hint extraction
+- Parallelized processing (2-4x speedup)
+- Interruptible with Ctrl+C (graceful cancellation)
+
+**Recent Improvements** (2025-11-30):
+
+- ✅ **Bundle Size Optimization**: 81% reduction (18MB → 3.4MB, 5.3x smaller) via test pattern extraction to OpenAPI contracts
+- ✅ **Acceptance Criteria Limiting**: 1-3 high-level items per story (detailed examples in contract files)
+- ✅ **KeyboardInterrupt Handling**: All parallel operations support immediate cancellation
+- ✅ **Semgrep Detection Fix**: Increased timeout from 1s to 5s for reliable detection
+- Async pattern detection
+- Theme detection from imports
+
+**Semgrep Pattern Detection** (Enhancement):
+
+- **API Endpoint Detection**: FastAPI, Flask, Express, Gin routes
+- **Database Model Detection**: SQLAlchemy, Django, Pydantic, TortoiseORM, Peewee
+- **CRUD Operation Detection**: Function naming patterns (create_*, get_*, update_*, delete_*)
+- **Authentication Patterns**: Auth decorators, permission checks
+- **Code Quality Assessment**: Anti-patterns, code smells, security vulnerabilities
+- **Framework Patterns**: Async/await, context managers, type hints, configuration
+
+**Plugin Status**: The import command displays plugin status (AST Analysis, Semgrep Pattern Detection, Dependency Graph Analysis) showing which tools are enabled and used.
+
+**Benefits**:
+
+- Framework-aware feature detection
+- Enhanced confidence scores (AST + Semgrep evidence)
+- Code quality maturity assessment
+- Multi-language ready (TypeScript, JavaScript, Go patterns available)
+
 ## Testing Strategy
 
 ### Contract-First Testing

docs/reference/commands.md

@@ -228,7 +228,7 @@ specfact import from-code [OPTIONS]
 
 - **CoPilot Mode** (AI-first - Pragmatic): Uses AI IDE's native LLM (Cursor, CoPilot, etc.) for semantic understanding. The AI IDE understands the codebase semantically, then calls the SpecFact CLI for structured analysis. No separate LLM API setup needed. Multi-language support, high-quality Spec-Kit artifacts.
 
-- **CI/CD Mode** (AST fallback): Uses Python AST for fast, deterministic analysis (Python-only). Works offline, no LLM required.
+- **CI/CD Mode** (AST+Semgrep Hybrid): Uses Python AST + Semgrep pattern detection for fast, deterministic analysis. Framework-aware detection (API endpoints, models, CRUD, code quality). Works offline, no LLM required. Displays plugin status (AST Analysis, Semgrep Pattern Detection, Dependency Graph Analysis).
 
 **Pragmatic Integration**:
 
@@ -265,12 +265,19 @@ specfact import from-code --bundle api-service \
 
 **What it does:**
 
-- Builds module dependency graph
-- Mines commit history for feature boundaries
-- Extracts acceptance criteria from tests
-- Infers API surfaces from type hints
-- Detects async anti-patterns with Semgrep
-- Generates plan bundle with confidence scores
+- **AST Analysis**: Extracts classes, methods, imports, docstrings
+- **Semgrep Pattern Detection**: Detects API endpoints, database models, CRUD operations, auth patterns, framework usage, code quality issues
+- **Dependency Graph**: Builds module dependency graph (when pyan3 and networkx available)
+- **Evidence-Based Confidence Scoring**: Systematically combines AST + Semgrep evidence for accurate confidence scores:
+  - Framework patterns (API, models, CRUD) increase confidence
+  - Test patterns increase confidence
+  - Anti-patterns and security issues decrease confidence
+- **Code Quality Assessment**: Identifies anti-patterns and security vulnerabilities
+- **Plugin Status**: Displays which analysis tools are enabled and used
+- **Optimized Bundle Size**: 81% reduction (18MB → 3.4MB, 5.3x smaller) via test pattern extraction to OpenAPI contracts
+- **Acceptance Criteria**: Limited to 1-3 high-level items per story, detailed examples in contract files
+- **Interruptible**: Press Ctrl+C during analysis to cancel immediately (all parallel operations support graceful cancellation)
+- Generates plan bundle with enhanced confidence scores
 
 **Partial Repository Coverage:**
 
@@ -988,11 +995,17 @@ specfact plan select --id abc123def456
 
 **What it does:**
 
-- Lists all available plan bundles in `.specfact/plans/` with metadata (features, stories, stage, modified date)
+- Lists all available plan bundles in `.specfact/projects/` with metadata (features, stories, stage, modified date)
 - Displays numbered list with active plan indicator
 - Applies filters (current, stages, last N) before display/selection
 - Updates `.specfact/plans/config.yaml` to set the active plan
-- The active plan becomes the default for all plan operations
+- The active plan becomes the default for all commands with `--bundle` option:
+  - **Plan management**: `plan compare`, `plan promote`, `plan add-feature`, `plan add-story`, `plan update-idea`, `plan update-feature`, `plan update-story`, `plan review`
+  - **Analysis & generation**: `import from-code`, `generate contracts`, `analyze contracts`
+  - **Synchronization**: `sync bridge`, `sync intelligent`
+  - **Enforcement & migration**: `enforce sdd`, `migrate to-contracts`, `drift detect`
+
+  Use `--bundle <name>` to override the active plan for any command.
 
 **Filter Options:**