fix: sidecar template code quality improvements (v0.20.5)

.cursor/commands/specfact.01-import.md

@@ -21,17 +21,20 @@ Import codebase → plan bundle. CLI extracts routes/schemas/relationships/contr
 
 ## Workflow
 
-1. **Execute CLI**: `specfact import from-code [<bundle>] --repo <path> [options]`
+1. **Execute CLI**: `specfact [GLOBAL OPTIONS] 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
+   - Note: `--no-interactive` is a global option and must appear before the subcommand (e.g., `specfact --no-interactive import from-code ...`).
    - **Auto-enrichment enabled by default**: Automatically enhances vague acceptance criteria, incomplete requirements, and generic tasks using PlanEnricher (same logic as `plan review --auto-enrich`)
    - Use `--no-enrich-for-speckit` to disable auto-enrichment
+   - **Contract extraction**: OpenAPI contracts are extracted automatically **only** for features with `source_tracking.implementation_files` and detectable API endpoints (FastAPI/Flask patterns). For enrichment-added features or Django apps, use `specfact contract init` after enrichment (see Phase 4)
 
-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/projects/<bundle-name>/reports/enrichment/` (bundle-specific, Phase 8.5, if created)
+2. **LLM Enrichment** (Copilot-only, before applying `--enrichment`):
+   - Read CLI artifacts: `.specfact/projects/<bundle>/enrichment_context.md`, feature YAMLs, contract scaffolds, and brownfield reports
+   - Scan the codebase within `--entry-point` (and adjacent modules) to identify missing features, dependencies, and behavior; do **not** rely solely on AST-derived YAML
+   - Compare code findings vs CLI artifacts, then add missing features/stories, reasoning, and acceptance criteria (each added feature must include at least one story)
+   - Save the enrichment report to `.specfact/projects/<bundle-name>/reports/enrichment/<bundle-name>-<timestamp>.enrichment.md` (bundle-specific, Phase 8.5)
+   - **CRITICAL**: Follow the exact enrichment report format (see "Enrichment Report Format" section below) to ensure successful parsing
 
 3. **Present**: Bundle location, report path, summary (features/stories/contracts/relationships)
 
@@ -42,7 +45,7 @@ Import codebase → plan bundle. CLI extracts routes/schemas/relationships/contr
 **Rules:**
 
 - Execute CLI first - never create artifacts directly
-- Use `--no-interactive` flag in CI/CD environments
+- Use the global `--no-interactive` flag in CI/CD environments (must appear before the subcommand)
 - Never modify `.specfact/` directly
 - Use CLI output as grounding for validation
 - Code generation requires LLM (only via AI IDE slash prompts, not CLI-only)
@@ -55,7 +58,7 @@ When in copilot mode, follow this three-phase workflow:
 
 ```bash
 # Execute CLI to get structured output
-specfact import from-code [<bundle>] --repo <path> --no-interactive
+specfact --no-interactive import from-code [<bundle>] --repo <path>
 ```
 
 **Capture**:
@@ -71,10 +74,10 @@ specfact import from-code [<bundle>] --repo <path> --no-interactive
 **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
+- Scan the codebase within `--entry-point` for missing features/behavior and compare against CLI artifacts
+- Identify missing features/stories and add reasoning/acceptance criteria (no direct edits to `.specfact/`)
+- Suggest confidence adjustments and extract business context
+- **CRITICAL**: Generate enrichment report in the exact format specified below (see "Enrichment Report Format" section)
 
 **What NOT to do**:
 
@@ -83,20 +86,159 @@ specfact import from-code [<bundle>] --repo <path> --no-interactive
 - ❌ Bypass CLI validation
 - ❌ Write to `.specfact/` folder directly (always use CLI)
 - ❌ Use direct file manipulation tools for writing (use CLI commands)
+- ❌ Deviate from the enrichment report format (will cause parsing failures)
 
 **Output**: Generate enrichment report (Markdown) saved to `.specfact/projects/<bundle-name>/reports/enrichment/` (bundle-specific, Phase 8.5)
 
+**Enrichment Report Format** (REQUIRED for successful parsing):
+
+The enrichment parser expects a specific Markdown format. Follow this structure exactly:
+
+```markdown
+# [Bundle Name] Enrichment Report
+
+**Date**: YYYY-MM-DDTHH:MM:SS  
+**Bundle**: <bundle-name>
+
+---
+
+## Missing Features
+
+1. **Feature Title** (Key: FEATURE-XXX)
+   - Confidence: 0.85
+   - Outcomes: outcome1, outcome2, outcome3
+   - Stories:
+     1. Story title here
+        - Acceptance: criterion1, criterion2, criterion3
+     2. Another story title
+        - Acceptance: criterion1, criterion2
+
+2. **Another Feature** (Key: FEATURE-YYY)
+   - Confidence: 0.80
+   - Outcomes: outcome1, outcome2
+   - Stories:
+     1. Story title
+        - Acceptance: criterion1, criterion2, criterion3
+
+## Confidence Adjustments
+
+- FEATURE-EXISTING-KEY: 0.90 (reason: improved understanding after code review)
+
+## Business Context
+
+- Priority: High priority feature for core functionality
+- Constraint: Must support both REST and GraphQL APIs
+- Risk: Potential performance issues with large datasets
+```
+
+**Format Requirements**:
+
+1. **Section Header**: Must use `## Missing Features` (case-insensitive, but prefer this exact format)
+2. **Feature Format**:
+   - Numbered list: `1. **Feature Title** (Key: FEATURE-XXX)`
+   - **Bold title** is required (use `**Title**`)
+   - **Key in parentheses**: `(Key: FEATURE-XXX)` - must be uppercase, alphanumeric with hyphens/underscores
+   - Fields on separate lines with `-` prefix:
+     - `- Confidence: 0.85` (float between 0.0-1.0)
+     - `- Outcomes: comma-separated or line-separated list`
+     - `- Stories:` (required - each feature must have at least one story)
+3. **Stories Format**:
+   - Numbered list under `Stories:` section: `1. Story title`
+   - **Indentation**: Stories must be indented (2-4 spaces) under the feature
+   - **Acceptance Criteria**: `- Acceptance: criterion1, criterion2, criterion3`
+     - Can be comma-separated on one line
+     - Or multi-line (each criterion on new line)
+     - Must start with `- Acceptance:`
+4. **Optional Sections**:
+   - `## Confidence Adjustments`: List existing features with confidence updates
+   - `## Business Context`: Priorities, constraints, risks (bullet points)
+5. **File Naming**: `<bundle-name>-<timestamp>.enrichment.md` (e.g., `djangogoat-2025-12-23T23-50-00.enrichment.md`)
+
+**Example** (working format):
+
+```markdown
+## Missing Features
+
+1. **User Authentication** (Key: FEATURE-USER-AUTHENTICATION)
+   - Confidence: 0.85
+   - Outcomes: User registration, login, profile management
+   - Stories:
+     1. User can sign up for new account
+        - Acceptance: sign_up view processes POST requests, creates User automatically, user is logged in after signup, redirects to profile page
+     2. User can log in with credentials
+        - Acceptance: log_in view authenticates username/password, on success user is logged in and redirected, on failure error message is displayed
+```
+
+**Common Mistakes to Avoid**:
+
+- ❌ Missing `(Key: FEATURE-XXX)` - parser needs this to identify features
+- ❌ Missing `Stories:` section - every feature must have at least one story
+- ❌ Stories not indented - parser expects indented numbered lists
+- ❌ Missing `- Acceptance:` prefix - acceptance criteria won't be parsed
+- ❌ Using bullet points (`-`) instead of numbers (`1.`) for stories
+- ❌ Feature title not in bold (`**Title**`) - parser may not extract title correctly
+
 ### 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
+specfact --no-interactive import from-code [<bundle>] --repo <path> --enrichment <enrichment-report>
 ```
 
 **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))
 
+### Phase 4: OpenAPI Contract Generation (REQUIRED for Sidecar Validation)
+
+**When contracts are generated automatically:**
+
+The `import from-code` command attempts to extract OpenAPI contracts automatically, but **only if**:
+
+1. Features have `source_tracking.implementation_files` (AST-detected features)
+2. The OpenAPI extractor finds API endpoints (FastAPI/Flask patterns like `@app.get`, `@router.post`, `@app.route`)
+
+**When contracts are NOT generated:**
+
+Contracts are **NOT** generated automatically when:
+
+- Features were added via enrichment (no `source_tracking.implementation_files`)
+- Django applications (Django `path()` patterns are not detected by the extractor)
+- Features without API endpoints (models, utilities, middleware, etc.)
+- Framework SDKs or libraries without web endpoints
+
+**How to generate contracts manually:**
+
+For features that need OpenAPI contracts (e.g., for sidecar validation with CrossHair), use:
+
+```bash
+# Generate contract for a single feature
+specfact --no-interactive contract init --bundle <bundle-name> --feature <FEATURE_KEY> --repo <path>
+
+# Example: Generate contracts for all enrichment-added features
+specfact --no-interactive contract init --bundle djangogoat-validation --feature FEATURE-USER-AUTHENTICATION --repo .
+specfact --no-interactive contract init --bundle djangogoat-validation --feature FEATURE-NOTES-MANAGEMENT --repo .
+# ... repeat for each feature that needs a contract
+```
+
+**When to apply contract generation:**
+
+- **After Phase 3** (enrichment applied): Check which features have contracts in `.specfact/projects/<bundle>/contracts/`
+- **Before sidecar validation**: All features that will be analyzed by CrossHair/Specmatic need OpenAPI contracts
+- **For Django apps**: Always generate contracts manually after enrichment, as Django URL patterns are not auto-detected
+
+**Verification:**
+
+```bash
+# Check which features have contracts
+ls .specfact/projects/<bundle>/contracts/*.yaml
+
+# Compare with total features
+ls .specfact/projects/<bundle>/features/*.yaml
+```
+
+If the contract count is less than the feature count, generate missing contracts using `contract init`.
+
 ## Expected Output
 
 **Success**: Bundle location, report path, summary (features/stories/contracts/relationships)  

.cursor/commands/specfact.02-plan.md

@@ -103,7 +103,9 @@ specfact plan <operation> [--bundle <name>] [options] --no-interactive
 **What to do**:
 
 - Read CLI-generated artifacts (use file reading tools for display only)
-- Research codebase for additional context
+- Use CLI artifacts as the source of truth for keys/structure/metadata
+- Scan codebase only if asked to align the plan with implementation or to add missing features
+- When scanning, compare findings against CLI artifacts and propose updates via CLI commands
 - Identify missing features/stories
 - Suggest confidence adjustments
 - Extract business context

.cursor/commands/specfact.03-review.md

@@ -131,6 +131,9 @@ For these cases, use the **export-to-file → LLM reasoning → import-from-file
 
 **CRITICAL**: Always use `/tmp/` for temporary artifacts to avoid polluting the codebase. Never create temporary files in the project root.
 
+**CRITICAL**: Question IDs are generated per run and can change if you re-run review.  
+**Do not** re-run `plan review` between exporting questions and applying answers. Always answer using the exact exported questions file for that session.
+
 **Note**: The `--max-questions` parameter (default: 5) limits the number of questions per session, not the total number of available questions. If there are more questions available, you may need to run the review multiple times to answer all questions. Each session will ask different questions (avoiding duplicates from previous sessions).
 
 **Export questions to file for LLM reasoning:**
@@ -393,6 +396,11 @@ specfact plan review [<bundle-name>] --list-questions --output-questions /tmp/qu
 
 **What to do**:
 
+0. **Grounding rule**:
+   - Treat CLI-exported questions as the source of truth; consult codebase/docs only to answer them (do not invent new artifacts)
+   - **Feature/Story Completeness note**: Answers here are clarifications only. They do **NOT** create stories.  
+     For missing stories, use `specfact plan add-story` (or `plan update-story --batch-updates` if stories already exist).
+
 1. **Read exported questions file** (`/tmp/questions.json`):
    - Review all questions and their categories
    - Identify questions requiring code/feature analysis
@@ -601,6 +609,102 @@ Create one with: specfact plan init legacy-api
 - Use `plan update-idea` to update idea fields directly
 - If bundle needs regeneration, use `import from-code --enrichment`
 
+**Note on OpenAPI Contracts:**
+
+After applying enrichment or review updates, check if features need OpenAPI contracts for sidecar validation:
+
+- Features added via enrichment typically don't have contracts (no `source_tracking`)
+- Django applications require manual contract generation (Django URL patterns not auto-detected)
+- Use `specfact contract init --bundle <bundle> --feature <FEATURE_KEY>` to generate contracts for features that need them
+
+**Enrichment Report Format** (for `import from-code --enrichment`):
+
+When generating enrichment reports for use with `import from-code --enrichment`, follow this exact format:
+
+```markdown
+# [Bundle Name] Enrichment Report
+
+**Date**: YYYY-MM-DDTHH:MM:SS  
+**Bundle**: <bundle-name>
+
+---
+
+## Missing Features
+
+1. **Feature Title** (Key: FEATURE-XXX)
+   - Confidence: 0.85
+   - Outcomes: outcome1, outcome2, outcome3
+   - Stories:
+     1. Story title here
+        - Acceptance: criterion1, criterion2, criterion3
+     2. Another story title
+        - Acceptance: criterion1, criterion2
+
+2. **Another Feature** (Key: FEATURE-YYY)
+   - Confidence: 0.80
+   - Outcomes: outcome1, outcome2
+   - Stories:
+     1. Story title
+        - Acceptance: criterion1, criterion2, criterion3
+
+## Confidence Adjustments
+
+- FEATURE-EXISTING-KEY: 0.90 (reason: improved understanding after code review)
+
+## Business Context
+
+- Priority: High priority feature for core functionality
+- Constraint: Must support both REST and GraphQL APIs
+- Risk: Potential performance issues with large datasets
+```
+
+**Format Requirements**:
+
+1. **Section Header**: Must use `## Missing Features` (case-insensitive, but prefer this exact format)
+2. **Feature Format**:
+   - Numbered list: `1. **Feature Title** (Key: FEATURE-XXX)`
+   - **Bold title** is required (use `**Title**`)
+   - **Key in parentheses**: `(Key: FEATURE-XXX)` - must be uppercase, alphanumeric with hyphens/underscores
+   - Fields on separate lines with `-` prefix:
+     - `- Confidence: 0.85` (float between 0.0-1.0)
+     - `- Outcomes: comma-separated or line-separated list`
+     - `- Stories:` (required - each feature must have at least one story)
+3. **Stories Format**:
+   - Numbered list under `Stories:` section: `1. Story title`
+   - **Indentation**: Stories must be indented (2-4 spaces) under the feature
+   - **Acceptance Criteria**: `- Acceptance: criterion1, criterion2, criterion3`
+     - Can be comma-separated on one line
+     - Or multi-line (each criterion on new line)
+     - Must start with `- Acceptance:`
+4. **Optional Sections**:
+   - `## Confidence Adjustments`: List existing features with confidence updates
+   - `## Business Context`: Priorities, constraints, risks (bullet points)
+5. **File Naming**: `<bundle-name>-<timestamp>.enrichment.md` (e.g., `djangogoat-2025-12-23T23-50-00.enrichment.md`)
+
+**Example** (working format):
+
+```markdown
+## Missing Features
+
+1. **User Authentication** (Key: FEATURE-USER-AUTHENTICATION)
+   - Confidence: 0.85
+   - Outcomes: User registration, login, profile management
+   - Stories:
+     1. User can sign up for new account
+        - Acceptance: sign_up view processes POST requests, creates User automatically, user is logged in after signup, redirects to profile page
+     2. User can log in with credentials
+        - Acceptance: log_in view authenticates username/password, on success user is logged in and redirected, on failure error message is displayed
+```
+
+**Common Mistakes to Avoid**:
+
+- ❌ Missing `(Key: FEATURE-XXX)` - parser needs this to identify features
+- ❌ Missing `Stories:` section - every feature must have at least one story
+- ❌ Stories not indented - parser expects indented numbered lists
+- ❌ Missing `- Acceptance:` prefix - acceptance criteria won't be parsed
+- ❌ Using bullet points (`-`) instead of numbers (`1.`) for stories
+- ❌ Feature title not in bold (`**Title**`) - parser may not extract title correctly
+
 ## Context
 
 {ARGS}

.cursor/commands/specfact.04-sdd.md

@@ -86,6 +86,7 @@ specfact plan harden [<bundle-name>] [--sdd <path>] --no-interactive
 **What to do**:
 
 - Read CLI-generated SDD (use file reading tools for display only)
+- Treat CLI SDD as the source of truth; scan codebase only to enrich WHY/WHAT/HOW context
 - Research codebase for additional context
 - Suggest improvements to WHY/WHAT/HOW sections
 

.cursor/commands/specfact.05-enforce.md

@@ -90,6 +90,7 @@ specfact enforce sdd [<bundle-name>] [--sdd <path>] --no-interactive
 **What to do**:
 
 - Read CLI-generated validation report (use file reading tools for display only)
+- Treat the CLI report as the source of truth; scan codebase only to explain deviations or propose fixes
 - Research codebase for context on deviations
 - Suggest fixes for validation failures
 

.cursor/commands/specfact.06-sync.md

@@ -93,6 +93,7 @@ specfact sync bridge --adapter <adapter> --repo <path> [options] --no-interactiv
 **What to do**:
 
 - Read CLI-generated sync results (use file reading tools for display only)
+- Treat CLI sync output as the source of truth; scan codebase only to explain conflicts
 - Research codebase for context on conflicts
 - Suggest resolution strategies
 

.cursor/commands/specfact.compare.md

@@ -90,6 +90,7 @@ specfact plan compare [--bundle <name>] [options] --no-interactive
 **What to do**:
 
 - Read CLI-generated comparison report (use file reading tools for display only)
+- Treat the comparison report as the source of truth; scan codebase only to explain or confirm deviations
 - Research codebase for context on deviations
 - Suggest fixes for missing features or mismatches
 

.cursor/commands/specfact.validate.md

@@ -92,6 +92,7 @@ specfact repro --repo <path> [options] --no-interactive
 **What to do**:
 
 - Read CLI-generated validation report (use file reading tools for display only)
+- Treat the validation report as the source of truth; scan codebase only to explain failures
 - Research codebase for context on failures
 - Suggest fixes for validation failures