specfact-cli 0.20.0__tar.gz → 0.20.5__tar.gz

{specfact_cli-0.20.0 → specfact_cli-0.20.5}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.20.0"
+version = "0.20.5"
 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.20.0 → specfact_cli-0.20.5}/resources/prompts/shared/cli-enforcement.md

@@ -37,6 +37,12 @@ These operations **require LLM** and are only available via AI IDE slash prompts
 **Access**: Only available via AI IDE slash prompts (Cursor, CoPilot, etc.)  
 **Pattern**: Slash prompt → LLM generates → CLI validates → Apply if valid
 
+## LLM Grounding Rules
+
+- Treat CLI artifacts as the source of truth for keys, structure, and metadata.
+- Scan the codebase only when asked to infer missing behavior/context or explain deviations; respect `--entry-point` scope when provided.
+- Use codebase findings to propose updates via CLI (enrichment report, plan update commands), never to rewrite artifacts directly.
+
 ## Rules
 
 1. **Execute CLI First**: Always run CLI commands before any analysis

specfact_cli-0.20.5/resources/prompts/specfact.01-import.md

@@ -0,0 +1,263 @@
+---
+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/--no-enrich-for-speckit` (default: enabled, uses PlanEnricher for consistent enrichment)  
+**Advanced/Configuration**: `--confidence FLOAT` (0.0-1.0), `--key-format FORMAT` (classname|sequential)
+
+## Workflow
+
+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** (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)
+
+## 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 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)
+
+## 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 --no-interactive import from-code [<bundle>] --repo <path>
+```
+
+**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)
+- 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**:
+
+- ❌ 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)
+- ❌ 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 --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)  
+**Error**: Missing bundle name or bundle already exists
+
+## Common Patterns
+
+```bash
+/specfact.01-import --repo .                    # Uses active plan, auto-enrichment enabled by default
+/specfact.01-import --bundle legacy-api --repo . # Auto-enrichment enabled
+/specfact.01-import --repo . --no-enrich-for-speckit  # Disable auto-enrichment
+/specfact.01-import --repo . --entry-point src/auth/
+/specfact.01-import --repo . --enrichment report.md
+```
+
+## Context
+
+{ARGS}

{specfact_cli-0.20.0 → specfact_cli-0.20.5}/resources/prompts/specfact.02-plan.md

@@ -107,7 +107,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

{specfact_cli-0.20.0 → specfact_cli-0.20.5}/resources/prompts/specfact.03-review.md

@@ -135,6 +135,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:**
@@ -397,6 +400,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
@@ -605,6 +613,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}

{specfact_cli-0.20.0 → specfact_cli-0.20.5}/resources/prompts/specfact.04-sdd.md

@@ -90,6 +90,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
 

{specfact_cli-0.20.0 → specfact_cli-0.20.5}/resources/prompts/specfact.05-enforce.md

@@ -94,6 +94,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
 

{specfact_cli-0.20.0 → specfact_cli-0.20.5}/resources/prompts/specfact.06-sync.md

@@ -97,6 +97,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
 

{specfact_cli-0.20.0 → specfact_cli-0.20.5}/resources/prompts/specfact.compare.md

@@ -94,6 +94,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
 

{specfact_cli-0.20.0 → specfact_cli-0.20.5}/resources/prompts/specfact.validate.md

@@ -96,6 +96,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
 

specfact_cli-0.20.5/resources/templates/sidecar/README.md

@@ -0,0 +1,187 @@
+# Sidecar Validation Templates
+
+Purpose: Run validation tools against a target repository without modifying its source.
+
+This template set is intended for Phase B validation and can be copied into a
+separate sidecar workspace. Use `.specfact/projects/<bundle>/contracts/` as the
+source of truth for API contracts (specmatic/OpenAPI).
+
+## Quick Start
+
+1. Copy this folder into a sidecar workspace, or run:
+
+```bash
+./sidecar-init.sh /path/to/sidecar /path/to/target/repo bundle-name
+```
+
+1. Export environment variables (or use the `.env` file created by `sidecar-init.sh`):
+
+```bash
+export REPO_PATH=/path/to/target/repo
+export BUNDLE_NAME=bundle-name
+export SEMGREP_CONFIG=/path/to/semgrep.yml   # optional
+export REPO_PYTHONPATH="/path/to/target/repo/src:/path/to/target/repo"
+export SIDECAR_SOURCE_DIRS="/path/to/target/repo/src"  # optional (defaults to src/)
+export PYTHON_CMD=python3  # optional (auto-detects venv if .venv/ or venv/ exists)
+export DJANGO_SETTINGS_MODULE=project.settings  # optional (auto-detected for Django projects)
+export SPECMATIC_CMD=/path/to/specmatic  # optional (CLI binary, or: "npx --yes specmatic")
+export SPECMATIC_JAR=/path/to/specmatic.jar  # optional (java -jar fallback)
+export SPECMATIC_CONFIG=/path/to/specmatic.yaml  # optional config file
+export SPECMATIC_TEST_BASE_URL=http://localhost:5000  # optional target
+export SPECMATIC_HOST=localhost  # optional target host
+export SPECMATIC_PORT=5000  # optional target port
+export SPECMATIC_TIMEOUT=30  # optional request timeout (seconds)
+export SPECMATIC_AUTO_STUB=1  # optional (default: 1) run stub when no target configured
+export SPECMATIC_STUB_HOST=127.0.0.1  # optional stub host
+export SPECMATIC_STUB_PORT=19000  # optional stub port
+export SPECMATIC_STUB_WAIT=15  # optional stub startup wait (seconds)
+export SIDECAR_APP_CMD="python -m your_app"  # optional app command to run
+export SIDECAR_APP_HOST=127.0.0.1  # optional app host
+export SIDECAR_APP_PORT=5000  # optional app port
+export SIDECAR_APP_WAIT=15  # optional app startup wait (seconds)
+export BINDINGS_PATH=/path/to/bindings.yaml  # optional bindings map
+export FEATURES_DIR=/path/to/features  # optional features dir (FEATURE-*.yaml)
+export CROSSHAIR_VERBOSE=1  # optional CrossHair debug output
+export CROSSHAIR_REPORT_ALL=1  # optional report all postconditions
+export CROSSHAIR_REPORT_VERBOSE=1  # optional report stack traces
+export CROSSHAIR_MAX_UNINTERESTING_ITERATIONS=50  # optional iteration budget
+export CROSSHAIR_PER_PATH_TIMEOUT=2  # optional per-path timeout
+export CROSSHAIR_PER_CONDITION_TIMEOUT=10  # optional per-condition timeout
+export CROSSHAIR_ANALYSIS_KIND=icontract  # optional kinds (comma-separated)
+export CROSSHAIR_EXTRA_PLUGIN=/path/to/plugin.py  # optional extra plugins
+export RUN_BASEDPYRIGHT=0  # optional toggle per tool (default: 0)
+export TIMEOUT_BASEDPYRIGHT=30  # optional per-tool timeout
+export GENERATE_HARNESS=1  # optional (default: 1)
+export HARNESS_PATH=harness_contracts.py  # optional
+export INPUTS_PATH=inputs.json  # optional
+export SIDECAR_REPORTS_DIR=/path/to/repo/.specfact/projects/bundle/reports/sidecar  # optional
+```
+
+1. Run the sidecar script:
+
+```bash
+./run_sidecar.sh
+```
+
+## Refreshing the Sidecar Workspace
+
+If you update templates (for example `adapters.py`, `run_sidecar.sh`, or the
+harness generator), re-initialize the sidecar workspace so the new templates
+are copied over:
+
+```bash
+./sidecar-init.sh /path/to/sidecar /path/to/target/repo bundle-name
+```
+
+Notes:
+
+- This overwrites existing template files in the sidecar workspace.
+- Preserve local changes (for example `bindings.yaml` or `.env`) before
+  re-running if you have custom edits.
+- Re-run `./run_sidecar.sh` with `GENERATE_HARNESS=1` if you want a fresh
+  `harness_contracts.py` and `inputs.json` after template updates.
+
+## Notes
+
+- CrossHair requires contracts (icontract/PEP316/deal) or registered contracts.
+  Use `harness_contracts.py` or `crosshair_plugin.py` to attach contracts
+  externally without touching production code.
+
+- **Dual CrossHair Analysis**: The sidecar runs CrossHair in two modes:
+  1. **Source code analysis**: Analyzes source directories directly to catch existing decorators
+     (beartype, icontract, PEP316, deal) already present in the codebase (e.g., SpecFact CLI dogfooding).
+  2. **Harness analysis**: Analyzes generated harness files to catch contracts added externally
+     for code without decorators (e.g., DjangoGoat, Flask, Requests).
+  
+  Both analyses are necessary for complete coverage:
+  - **Case A**: Code with existing decorators → CrossHair analyzes source directly
+  - **Case B**: Code without decorators → CrossHair analyzes harness with externally-added contracts
+- Specmatic contracts are expected in:
+  `<REPO_PATH>/.specfact/projects/<BUNDLE_NAME>/contracts/`
+- If you only have the Python `specmatic` package installed, note it does not
+  expose a CLI or module runner. Provide a CLI path (`SPECMATIC_CMD`), use `npx`,
+  or supply a jar (`SPECMATIC_JAR`) to execute Specmatic in the sidecar.
+- For contract tests that hit a running service, set `SPECMATIC_TEST_BASE_URL`
+  (or `SPECMATIC_HOST`/`SPECMATIC_PORT`) so Specmatic knows where to send requests.
+- If you don't have a target service, the sidecar can auto-start a Specmatic
+  stub (`SPECMATIC_AUTO_STUB=1`) or launch a real service with `SIDECAR_APP_CMD`.
+- All reports/logs should be written to SpecFact bundle reports, not into the
+  target repo.
+
+## CrossHair Defaults (Suggested)
+
+These defaults provide stable results for most repositories; tune them if your
+codebase is large or has heavy initialization.
+
+```bash
+export CROSSHAIR_ANALYSIS_KIND=icontract
+export CROSSHAIR_PER_PATH_TIMEOUT=2
+export CROSSHAIR_PER_CONDITION_TIMEOUT=10
+export CROSSHAIR_MAX_UNINTERESTING_ITERATIONS=50
+export CROSSHAIR_REPORT_ALL=1
+export CROSSHAIR_REPORT_VERBOSE=0
+```
+
+## Tool Toggles & Timeouts
+
+The sidecar runner supports basic toggles (set to `0` to skip):
+
+- `RUN_SEMGREP`, `RUN_BASEDPYRIGHT`, `RUN_SPECMATIC`, `RUN_CROSSHAIR`
+- `GENERATE_HARNESS` (generate `harness_contracts.py` and `inputs.json` from OpenAPI)
+
+And per-tool timeouts in seconds:
+
+- `TIMEOUT_SEMGREP`, `TIMEOUT_BASEDPYRIGHT`, `TIMEOUT_SPECMATIC`, `TIMEOUT_CROSSHAIR`
+
+## Harness Generation
+
+The harness is auto-generated from OpenAPI contracts in:
+`<REPO_PATH>/.specfact/projects/<BUNDLE_NAME>/contracts/`
+
+Generated outputs (in the sidecar workspace):
+
+- `harness_contracts.py` (CrossHair harness)
+- `inputs.json` (deterministic example requests/responses)
+- `bindings.yaml` (optional mapping to real code)
+
+Bindings let you attach harness functions to real code without editing the repo.
+If `bindings.yaml` is present, the harness will call the bound function instead
+of returning a fixed example.
+
+Binding schema (minimal):
+
+```yaml
+bindings:
+  - operation_id: create_item
+    target: your_package.factory:ItemFactory
+    method: create
+    factory:
+      args: ["$request.item_type"]
+    call_style: kwargs
+```
+
+Optional keys:
+
+- `adapter`: name of a function in `adapters.py` to handle complex setup.
+- `factory.target`: alternate factory callable (module:func) to create instance.
+- `factory.args` / `factory.kwargs`: supports `$request.<key>` or `$env.<VAR>` values.
+
+Available adapters (see `adapters.py` for config fields):
+
+- `call_method_with_factory`: construct instance then call method.
+- `call_constructor_then_method`: construct instance via `init` and call method.
+- `call_classmethod`: call a classmethod/staticmethod on a class target.
+- `call_with_context_manager`: create resource in `with` block then call method.
+- `call_async`: call async function and run the coroutine.
+- `call_with_setup_teardown`: run setup/teardown around a target call.
+- `call_with_request_transform`: rename/drop/set/coerce request fields before call.
+- `call_generator`: consume a generator/iterator and return list/last/count.
+- `call_from_registry`: resolve a callable from a registry/entrypoint map.
+- `call_with_overrides`: temporarily override module attributes during a call.
+- `call_with_contextvars`: set context variables for the call duration.
+- `call_with_session`: create a session/transaction around the call.
+- `call_with_callbacks`: inject callbacks into the request payload.
+
+Logs are written to:
+
+- `<REPO_PATH>/.specfact/projects/<BUNDLE_NAME>/reports/sidecar/`