feat(release): working on next release

Author: Mte90

.gitignore

@@ -9,3 +9,4 @@ findings.json
 checkpoint.json
 file_hashes.json
 .cortexkit
+todo.md

CHANGELOG.md

@@ -7,28 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- VulnInstruct specification-guided vulnerability detection (`src/vuln_spec` module: schema, extractor, BM25+vector retriever) behind `[vuln_spec] enabled = false` default
+
+### Changed
+- Threat-modeling phase disabled by default (`enable_threat_modeling = false`) — it generated a static STRIDE template rather than code-derived analysis
+
 ## [1.1.0] - 2026-08-12
 
 ### Added
 - 24-phase scanner pipeline with Validate phase
 - P1-P5 paper integration tracks (VulTriage, VulnLLM-R, MoCQ, PacVD, AgentFlow) behind `enabled = false` defaults
 - `max_reasoning_tokens` field for LLM config
 - Agent scaffold modules: `call_graph_paths`, `fn_lookup`
-- 63 unit tests for agent_scaffold edge cases
-- Example report screenshot in README
-- `docs/README.md` index and `docs/roadmap.md`
+- `docs/README.md` documentation index
 
 ### Changed
-- Split large source files (>1000 lines) into directory modules: `other_phases/`, `llm_phases/`, `config/`
-- Extracted shared tree-sitter parser module
-- Moved inline tests from source files to `tests/`
+- Internal refactoring: split oversized modules into directory modules, extracted shared tree-sitter parser, consolidated tests under `tests/`
 - MSRV-compatible clippy fixes (replaced `is_none_or`, `is_multiple_of`)
 
 ### Fixed
 - C function-name extraction handles `function_declarator` tree-sitter node
 - Call-graph builder treats uncalled functions as entry points
 - Phase count references updated from 20 to 24 throughout
-
-### Removed
-- Duplicate inline test blocks from `ai_aggregation.rs`, `multi_verifier.rs`, `root_cause_dedup.rs`
-- Orphaned `scanner_phases_consolidated.rs` artifact

docs/architecture.md

@@ -11,39 +11,36 @@ BACO uses a **data-driven PhaseGraph** (`src/scanner/pipeline/orchestrator.rs`)
 
 ## Pipeline Phases
 
-**Core Pipeline (20 phases):**
-
-### Parallel Detection (3 phases)
-1. **Indexing**: Build file list and call graph
-2. **Semgrep**: Static analysis with predefined rules
-3. **LLM Static Analysis**: Independent LLM-based code analysis
-
-### Sequential Discovery (3 phases)
-4. **CWE Routing**: Mixture-of-experts routing to appropriate analyzers
-5. **LLM Discovery**: Multi-model vulnerability detection with CVE enrichment
-6. **LLM Verification**: Validation with PoC generation and mitigation code
-
-### Triage (5 phases)
-7. **SecurityAgent Verification**: Tool-based agent verification using file_read, pattern_search, file_write, run_test
-8. **Ticket Cross-Ref**: Search GitHub/GitLab for existing reports
-9. **Git Analysis**: Check commit history for related fixes
-10. **Cross-File Analysis**: Trace data flow between files
-11. **Confidence Scoring**: Calculate composite reliability score
-
-### Aggregation (2 phases)
-12. **AI Aggregation**: Generate executive summary, semantic deduplication, and LLM-enriched descriptions
-13. **Threat Modeling**: Generate THREAT_MODEL.md with attack surface analysis
-
-### Post-Processing (6 phases)
-14. **Root Cause Dedup**: Deduplicate findings by root cause instead of location
-15. **Multi-Verifier**: Multiple verification methods with majority voting
-16. **Auto-Patching**: Generate and validate patches with staging
-17. **CVE Bootstrap**: Enrich findings with NVD/CISA KEV data
-18. **PoC Compiler**: Verify PoC code compiles successfully
-19. **Variant Search**: Search for related vulnerability variants
-
-### Output (1 phase)
-20. **Reporting**: Generate JSON, HTML, and SARIF outputs
+**Core Pipeline (24 phases):**
+
+Phase order is defined once in `PhaseGraph::new()` (src/scanner/pipeline/orchestrator.rs); this table mirrors it and must be updated when that changes.
+
+| Phase # | Name | Parallel/Sequential | Config gate (default) |
+|---------|------|---------------------|----------------------|
+| 1 | Indexing | Parallel | Always-on |
+| 2 | Semgrep | Parallel | Always-on |
+| 3 | CPG Slice | Parallel | `cpg.enabled=false` |
+| 4 | LLM Static Analysis | Parallel | `llm.phases.indexing` (API key present) |
+| 5 | CWE Routing | Sequential | Always-on |
+| 6 | Rule Synthesis | Sequential | `rulesynth.enabled=false` |
+| 7 | LLM Discovery | Sequential | `llm.phases.discovery` (API key present) |
+| 8 | LLM Verification | Sequential | `llm.phases.verification` (API key present) |
+| 9 | Validate | Sequential | `validate.enabled=false` |
+| 10 | SecurityAgent Verification | Sequential | `agent.enabled=false` |
+| 11 | Ticket Cross-Reference | Sequential | `llm.phases.ticket_crossref` (API key present) |
+| 12 | Git Analysis | Sequential | `llm.phases.git_analysis` (API key present) |
+| 13 | Cross-File Analysis | Sequential | `llm.phases.cross_file_analysis` (API key present) |
+| 14 | Confidence Scoring | Sequential | `normalization.enabled=false` |
+| 15 | AI Aggregation | Sequential | `llm.phases.aggregation` (API key present) |
+| 16 | Threat Modeling | Sequential | `aggregation.tier_2_features.enabled=false` |
+| 17 | Root Cause Deduplication | Sequential | `aggregation.root_cause_dedup=true` |
+| 18 | Multi-Verifier | Sequential | `aggregation.multi_verifier=true` |
+| 19 | Auto-Patching | Sequential | `aggregation.auto_patching=false` |
+| 20 | CVE Bootstrap | Sequential | `aggregation.cve_bootstrap=true` |
+| 21 | PoC Compilation | Sequential | `aggregation.poc_compilation=false` |
+| 22 | Exploit Synthesis | Sequential | `exploit.enabled=false` |
+| 23 | Variant Search | Sequential | `aggregation.variant_search=true` |
+| 24 | Reporting | Sequential | Always-on |
 
 ## Data Flow
 
@@ -96,4 +93,3 @@ flowchart LR
 
 **Checkpoint markers**: Checkpoints are saved after each major phase, enabling resume from any point in the pipeline.
 
-**Orphaned phases**: The following modules exist but are NOT wired into the pipeline and do NOT run: CpgSlice, Hunt, Validate, IndependentVerify, ExploitSynth, RuleSynthesis.

docs/configuration.md

@@ -1,5 +1,37 @@
 # Configuration
 
+## Quick Start
+
+Minimal working configuration — copy-paste this block and fill in your API key:
+
+```toml
+[project]
+name = "my-project"
+path = "/path/to/target"
+languages = ["c"]
+
+[llm.phases.discovery]
+base_url = "https://api.mistral.ai/v1"
+api_key = "${MISTRAL_API_KEY}"
+model = "mistral-small"
+
+[scanner.performance]
+enable_incremental_scan = false
+max_parallel_tasks = 4
+enable_llm_cache = false
+enable_file_filtering = true
+```
+
+**Experimental sections** (disabled by default):
+- `[cpg]` — CPG-guided slicing (requires Joern binary)
+- `[validate]` — LLM-as-judge rationale validation
+- `[vuln_spec]` — VulTriage triple-path, policy sampling, agent scaffold
+- `[agent_scaffold]` — Agent-assisted analysis
+- `[agent_flow]` — Multi-agent harness synthesis
+- `[threat_modeling]` — STRIDE threat modeling (now under `[scanner.performance]`)
+
+Enable only after reviewing the detailed sections below.
+
 ## Project Settings
 
 ```toml
@@ -28,7 +60,7 @@ enable_file_filtering = true
 # Each flag controls whether a specific analysis phase runs during the scan.
 
 # Threat modeling using STRIDE analysis (adds LLM-based threat identification)
-enable_threat_modeling = true
+enable_threat_modeling = false
 # Root-cause deduplication (collapses findings that share the same root cause)
 enable_root_cause_dedup = true
 # Multi-verifier cross-checking (runs additional LLM verification passes)
@@ -49,7 +81,7 @@ enable_variant_search = true
 
 | Flag | Default | Side effects |
 | --- | --- | --- |
-| `enable_threat_modeling` | `true` | None (read-only analysis) |
+| `enable_threat_modeling` | `false` | None (read-only analysis) |
 | `enable_root_cause_dedup` | `true` | None |
 | `enable_multi_verifier` | `true` | Additional LLM API calls |
 | `enable_auto_patching` | `false` | Writes code files, runs git commands in a staging worktree |
@@ -64,14 +96,18 @@ See [`docs/architecture.md`](architecture.md) for the full 20-phase pipeline des
 
 BACO supports single or multiple models per phase. When multiple models are configured, they are used in round-robin fashion to distribute load across different models/providers.
 
-**Detailed error logging**: When LLM requests fail, BACO reports the HTTP status code, error type (timeout, connection, request, body, decode), and the actual URL for easier debugging.
+**Default temperature:** `0.5` (controlled randomness for better security analysis)
+
+**Default max_reasoning_tokens:** `2048` (caps reasoning phase before forcing final answer)
 
 **Single model:**
 ```toml
 [llm.phases.discovery]
 base_url = "https://api.mistral.ai/v1"
 api_key = "${MISTRAL_API_KEY}"  # or set env var
 model = "mistral-small"
+temperature = 0.5
+max_reasoning_tokens = 2048
 ```
 
 **Multiple models:**
@@ -104,9 +140,10 @@ When enabled, the LLM Discovery phase reads source files directly before analyzi
 
 ```toml
 [agent]
-enabled = true
+enabled = false
 max_turns = 10           # Max conversation turns with tools
 tool_timeout_secs = 60   # Timeout for tool execution
+trusted_paths = ["."]    # Paths allowed for tool operations
 keep_artifacts = false   # Keep generated test files
 ```
 
@@ -158,22 +195,41 @@ Code:
 llm_discovery = """Given this finding, determine if it's a true vulnerability:
 Title: %%FINDING_TITLE%%
 Location: %%FILE_PATH%%:%%LINE_NUMBER%%
+Current Description: %%CURRENT_DESCRIPTION%%
 Description: %%VULNERABILITY_DESCRIPTION%%
 """
 ```
 
 **Available template variables:**
 - `%%PROJECT_PATH%%` - Target project path
+- `%%PROJECT_NAME%%` - Project name
 - `%%FILE_EXTENSIONS%%` - Detected file extensions
 - `%%LANGUAGES%%` - Target languages
 - `%%CODE_CONTENT%%` - Code snippet being analyzed
 - `%%LANGUAGE%%` - Programming language of the file
 - `%%FILE_PATH%%` - File path
-- `%%LINE_RANGE%%` - Line numbers
+- `%%LINE_NUMBER%%` - Specific line number
+- `%%LINE_RANGE%%` - Line numbers range
+- `%%CURRENT_DESCRIPTION%%` - Current vulnerability description (for iterative phases)
 - `%%FINDING_TITLE%%` - Vulnerability title
 - `%%VULNERABILITY_DESCRIPTION%%` - Description text
 - `%%FINDINGS_COUNT%%` - Total findings count
 - `%%SCAN_DATE%%` - Scan date
+- `%%TOTAL_FINDINGS%%` - Total findings count (alias)
+- `%%TOTAL_FILES%%` - Total files scanned
+- `%%FILES_COUNT%%` - Files count (alias)
+- `%%SOURCE_LIST%%` - List of source files
+- `%%CONTEXT_LINES%%` - Context lines around finding
+- `%%CWE_SPECS%%` - CWE specification details
+- `%%EXCLUDE_PATHS%%` - Excluded paths
+- `%%MAX_FILE_SIZE%%` - Maximum file size limit
+- `%%PROJECT_TYPE%%` - Project type
+- `%%SCAN_DURATION%%` - Scan duration
+- `%%TICKET_SYSTEMS%%` - Configured ticket systems
+- `%%TOOLS_USED%%` - Tools used in analysis
+- `%%VULNERABILITY_LIST%%` - List of vulnerabilities
+- `%%VULNERABILITY_TITLE%%` - Vulnerability title
+- `%%FINDINGS_LIST%%` - Full findings list
 
 Prompts are validated (max 10,000 characters, no null bytes) before use.
 
@@ -188,16 +244,26 @@ credentials.token = "${GITHUB_TOKEN}"
 
 ## Output Formats
 
-- **findings.json**: Complete vulnerability data with all 16 fields
-- **report.html**: Visual report with severity colors, code snippets, AI summary
 - **findings.json**: Complete vulnerability data with all 16 fields
 - **report.html**: Visual report with severity colors, code snippets, AI summary
 - **report.sarif**: SARIF format for CI/CD integration
 
 ## Paper-Integration Research Flags
 
-The following flags enable experimental research-backed analysis augmentations.
-All default to disabled. See `todo.md` for full implementation details.
+> **Experimental — disabled by default.** These sections enable research-backed analysis augmentations. Enable only after understanding the tradeoffs.
+
+### Validate (CORRECT paper arxiv:2504.13474)
+
+LLM-as-judge rationale validation: evaluates the soundness of reasoning behind each finding and adjusts confidence accordingly (+0.10 sound, -0.20 flawed).
+
+| Field    | Type | Default | Description                    |
+|----------|------|---------|--------------------------------|
+| `enabled`| bool | false   | Enable Validate phase          |
+
+```toml
+[validate]
+enabled = false
+```
 
 ### VulTriage (P1) — arXiv:2605.09461
 
@@ -276,15 +342,33 @@ feedback → iterative loop. Extends the `[scanner.rulesynth]` section.
 |-----------------|------|---------|--------------------------------|
 | `mocq_mode`     | bool | false   | Enable MoCQ neuro-symbolic mode|
 | `max_iterations`| int  | 5       | Max synthesis iterations       |
-| `corpus_path`   | str  | "tests/fixtures/" | Path to pattern corpus   |
+| `corpus_path`   | str  | None    | Path to pattern corpus         |
 
 ```toml
 [scanner.rulesynth]
+enabled = false
 mocq_mode = false
 max_iterations = 5
 corpus_path = "tests/fixtures/"
 ```
 
+### CPG-Guided Slicing (T3.1)
+
+CPG (Code Property Graph) slicing using Joern. Requires Joern binary in PATH or specify path.
+
+| Field         | Type | Default | Description                    |
+|---------------|------|---------|--------------------------------|
+| `enabled`     | bool | false   | Enable CPG slicing             |
+| `joern_path`  | str  | None    | Path to Joern binary           |
+| `slice_budget_lines`| int | 200  | Maximum lines per slice      |
+
+```toml
+[cpg]
+enabled = false
+joern_path = null
+slice_budget_lines = 200
+```
+
 ### PacVD Primitive-API Abstraction (P4) — arXiv:2605.07785
 
 Appends callee abstraction at one of four granularity levels to the LLM prompt.
@@ -319,4 +403,40 @@ integration — static harness only until P5.5.
 enabled = false
 max_iterations = 10
 requires_instrumented_target = false
+```
+
+### Exploit Synthesis (T3.2)
+
+Automated exploit generation to verify findings. Runs in sandboxed Docker containers.
+
+| Field                        | Type | Default | Description                    |
+|------------------------------|------|---------|--------------------------------|
+| `enabled`                    | bool | false   | Enable exploit synthesis       |
+| `sandbox_image`              | str  | "python:3.11-slim" | Docker image for sandbox |
+| `timeout_secs`               | int  | 30      | Timeout for exploit execution  |
+| `max_exploits_per_finding`   | int  | 1       | Max attempts per finding       |
+
+```toml
+[exploit]
+enabled = false
+sandbox_image = "python:3.11-slim"
+timeout_secs = 30
+max_exploits_per_finding = 1
+```
+
+### Confidence Normalization
+
+Normalizes confidence scores using project baselines or isotonic regression.
+
+| Field                  | Type | Default | Description                    |
+|------------------------|------|---------|--------------------------------|
+| `enabled`              | bool | false   | Enable normalization           |
+| `normalization_tier`   | str  | "None"  | Normalization tier (None, ProjectRelative, Isotonic) |
+| `project_baseline_path`| str  | None    | Path to project baseline file  |
+
+```toml
+[normalization]
+enabled = false
+normalization_tier = "None"
+project_baseline_path = null
 ```