Semantic Agent Cognitive Layer (MVP)

Local Rust service for deterministic code retrieval by symbol, span, and logic graph.

IDE Semantic-First Integration

Use the semantic-first integration guide for RooCode/KiloCode/Codex/Claude wiring, middleware policy controls, and end-to-end flow diagrams:

• docs/IDE_SEMANTIC_FIRST.md
• docs/TOOL_CALLING_GUIDE.md (objective + usage of API and MCP tool callings)
• docs/AB_TEST_DEV_RESULTS.md (development benchmark history and latest metrics)

Modules

• engine shared contracts
• parser Tree-sitter extraction
• storage SQLite + Tantivy
• indexer repo indexing orchestration
• retrieval operation handlers
• watcher incremental file updates
• api Axum JSON service

Implemented semantic layers now include logic nodes, persisted control/data-flow edges, semantic node labels, and graph-backed clustering/ranking.

Run

cargo run -p api -- ./test_repo

Service binds to $SEMANTIC_API_BASE_URL.

CLI-First Usage

semantic_cli is now the primary local entrypoint. It bootstraps the same shared application layer that powers the compatibility API and MCP adapters.

Install On Another Machine Or Project

The fastest local install path today is still Rust-native:

cargo install --path semantic_cli --locked --force --bin semantic

There is also a helper script in this repo:

powershell -ExecutionPolicy Bypass -File scripts/install.ps1 -Force

That installs a semantic binary into your Cargo bin directory, so you can point it at any other project without moving the Semantic repo:

semantic --repo C:\path\to\other-project status
semantic --repo C:\path\to\other-project route --task "explain auth flow"
semantic --repo C:\path\to\other-project serve api

Normal CLI use now reuses an existing local index by default. If .semantic/semantic.db already has indexed files, semantic status, semantic retrieve, semantic route, and semantic serve ... reuse that index instead of forcing a full repo refresh on every invocation. Use semantic index when you want an explicit refresh.

semantic status now also avoids first-run indexing entirely. On an unindexed repo it reports:

• index_available: false
• indexed_file_count: 0
• bootstrap_index_action: skip_bootstrap_refresh

That makes status usable as a shallow preflight even on large repos before a full index exists.

Recommended broader-reliability workflow:

• keep this repository as the Semantic source/install repo
• run semantic --repo <other-project> ... against external repos
• let each target repo build its own local .semantic/ runtime state
• rerun semantic --repo <other-project> status first when you want a quick preflight

Notes:

• telemetry and test_planner remain in-tree because they are active workspace members today
• test_coverage, test_fixtures, and evolution_graph can be ignored locally, but tracked files already in git will still remain tracked until deliberately removed from the repository history/workspace
• .semantic/semantic.db and .semantic/tantivy/ are generated runtime state; deleting them is safe when you want a clean re-index
• initial indexing currently uses full_with_default_excludes / source_focused mode by default for broad external repos, which means obvious heavyweight paths such as node_modules/, target/, build outputs, caches, and common binary artifacts are skipped on the first pass

cargo run -p semantic_cli -- --repo ./test_repo/todo_app status
cargo run -p semantic_cli -- --repo ./test_repo/todo_app retrieve --op SearchSymbol --name addTask
cargo run -p semantic_cli -- --repo ./test_repo/todo_app route --task "add due date to tasks"

status output now also surfaces large-repo onboarding state directly:

• indexing_mode
• indexing_completeness
• bootstrap_index_action
• indexed_path_hints
• index_region_status
• indexed_region_hints

Current values are:

• indexing_mode: full_with_default_excludes
• indexing_completeness: source_focused
• bootstrap_index_action: reuse_existing|bootstrap_full|skip_bootstrap_refresh
• indexed_path_hints: ... for the currently indexed directories/files
• index_region_status: unindexed|fully_indexed|targeted_partial|indexed_unknown_scope
• indexed_region_hints: ... for the explicitly targeted regions when partial indexing is in use

When no index exists yet, shallow navigation is still available through:

• get_directory_brief
• get_file_brief

Those operations now fall back to direct filesystem inspection for supported source/doc files, so Semantic can provide lightweight navigation context before a full index is built.

You can also build only the first region you care about:

semantic --repo C:\path\to\repo index --path src/auth
semantic --repo C:\path\to\repo index --path src/auth --path packages/api

Targeted indexing updates only the requested files/directories and keeps the rest of the repo unindexed until you explicitly expand coverage.

After targeted indexing, semantic status will surface those ready regions through indexed_path_hints, for example:

indexed_path_hints: src/auth | packages/api/src

Those hint summaries are presentation-only. They now suppress internal/generated paths such as .semantic/, .claude/, and fixture worktree internals so staged onboarding keeps real source roots prominent. Coverage truth, stored index contents, and index_region_status remain unchanged.

Retrieve and route flows now also surface coverage boundaries directly:

• index_readiness
• index_region_status
• index_recovery_mode
• index_recovery_target_kind
• index_recovery_delta
• index_coverage
• index_coverage_target
• suggested_index_command

For partially indexed repos, route verification can now surface:

• target_path_not_indexed

That makes partial indexing explicit in normal CLI use instead of only degrading implicitly when a request points outside the indexed region. When coverage is missing, Semantic now also suggests the exact next command to run, for example:

index_follow_up: semantic index --path src/worker

index_readiness is the compact machine-readable summary:

• unindexed_repo
• target_ready
• partial_index_missing_target
• indexed_repo

index_recovery_mode describes what Semantic did about missing coverage:

• none
• suggest_only
• auto_index_applied
• auto_index_attempted_no_change

index_recovery_delta summarizes what newly entered the indexed set after a successful auto-index retry:

• added_file_count
• changed_files

changed_files uses the same presentation filter as indexed_path_hints, so internal runtime paths do not crowd out the user-facing recovery summary. added_file_count still reflects the full indexed delta.

index_recovery_target_kind tells you whether the recovery target was:

• file
• directory

If you want Semantic to repair that gap automatically once, route and retrieve now support an explicit opt-in:

semantic --repo C:\path\to\repo route --task "understand src/worker job.ts" --auto-index-target
semantic --repo C:\path\to\repo retrieve --op get_directory_brief --path src/worker --auto-index-target

When that retry genuinely improves coverage, text output includes:

auto_index: applied @ src/worker

If the target still does not exist or remains uncovered, Semantic keeps the original unindexed warning instead of falsely claiming the retry succeeded. When the request names an exact file path, the retry now stays file-scoped instead of widening to the containing directory.

That means Semantic indexed the source-focused subset of the repo with heavyweight/generated paths excluded by default. This is an onboarding safeguard, not a claim of full staged/lazy indexing yet.

route text output now includes live verification state. When Semantic thinks the returned context needs manual inspection, the CLI prints a compact verification: needs_review line plus the recommended action. It also prints a compact verification_scope line showing the selected symbol and top file, a mutation_safety line for edit-capable routes, and, when mutation neighborhood verification fails, a compact verification_graph_issue line showing which files or symbols were missing or extra. Verbose mode adds exact verification checks like target_in_file=true, target_span=false, and scope_graph=false, plus a verification_graph_diff line with the full expected-vs-actual neighborhood summary. Use --output json for the full verification block and machine-readable issues.

For automation-heavy local flows, route also supports verification gates:

• --require-high-confidence exits non-zero unless the live verification status is high_confidence
• --min-verification needs_review allows needs_review and high_confidence, but still fails on weaker states like low_confidence, no_context_refs, or fallback_search
• --require-mutation-ready exits non-zero unless an edit-capable route is explicitly marked mutation_safety: ready

When a gate is used, route text output prints compact summary lines like verification_gate: min=needs_review actual=needs_review and mutation_gate: min=ready actual=blocked before any non-zero exit, so CI or local logs still show why the run was accepted or rejected.

For blocked implement or refactor routes, Semantic now also attempts a deterministic exact retry before giving up. If that retry can confirm the target through file outline or exact symbol lookup, the route is promoted to mutation_safety: ready and the retry evidence is attached in the verification metadata.

Quality status is also available directly from the CLI without booting the full runtime path:

cargo run -p semantic_cli -- --repo . status --quality
cargo run -p semantic_cli -- --repo . status --quality --output json

This reads the locally generated quality snapshot and reports the current stable|watch|drifting health plus recent retrieval/route latency deltas. The status output now splits that top-level health into latency_health and graph_drift_health, includes a compact machine-readable diagnosis such as clean, latency_only_drift, graph_only_drift, or mixed_drift, and surfaces an action_recommendation such as no_action, watch_latency, inspect_graph_drift, inspect_incomplete_mutation_scope, investigate_mixed_regression, or investigate_mixed_incomplete_mutation_scope, plus an action_priority, triage_path, action_target, action_primary_command, command categories, source artifacts, concrete latency_hotspot / graph_drift_hotspot hints with companion bucket ids, and a summary_lookup_hint plus summary_lookup_scope when there is something specific to inspect first. In incomplete-mutation cases, the lookup scope now narrows to mutation_scope_bucket, the source-artifact list expands to include the full quality report JSON, and the lookup hint points at a stable mutation-scope-bucket: <fixture>__mutation_scope label in the markdown summary so local triage can inspect mutation trust coverage directly instead of only the broader graph-drift summary surface. The snapshot also carries an action_checklist and action_commands list for non-clean runs, so local runs and scripts can move directly from classification to next step. When mutation-neighborhood drift exists, it also surfaces the current leading_graph_drift mode directly in the status output, a compact graph_drift_trend line showing whether that failure shape is worsening, improving, flat, or newly appearing versus the recent trailing average, fixture-aware drift lines so you can see which repo shape is moving most and, when applicable, which fixture is currently worsening fastest, and a separate mutation_scope_incomplete_rate so local automation can distinguish incomplete mutation neighborhoods from the older missing/extra graph-drift buckets. The JSON form also includes latency_score, latency_score_delta_vs_trailing, latency_score_direction, latency_severity, latency_severity_reason, graph_drift_score, graph_drift_score_delta_vs_trailing, graph_drift_score_direction, graph_drift_severity, and graph_drift_severity_reason fields so local automation can threshold, sort, and trend both performance and graph-drift pressure without parsing the human-readable trend text. The local quality exporter now does one unmeasured warmup pass per route/retrieval case before recording best-of-N latency, so the snapshot reflects warmed Semantic behavior instead of repeatedly overreacting to per-case cold-start cost. Local artifacts are written under docs/doc_ignore/:

The current status --quality --output json contract is:

• identity and state: kind, snapshot_path, status, health, latency_health, graph_drift_health, diagnosis
• actioning: action_recommendation, action_priority, triage_path, action_target
• executable triage: action_checklist, action_commands, action_primary_command
• command metadata: action_command_categories, action_primary_command_category
• artifact metadata: action_source_artifacts, summary_lookup_hint, summary_lookup_scope
• latency triage: latency_hotspot, latency_hotspot_bucket_id, latency_severity, latency_severity_reason, latency_score, latency_score_delta_vs_trailing, latency_score_direction
• graph-drift triage: graph_drift_hotspot, graph_drift_hotspot_bucket_id, leading_graph_drift, leading_graph_drift_fixture, graph_drift_trend, graph_drift_fixture_trend, top_worsening_graph_drift_fixture, graph_drift_severity, graph_drift_severity_reason, graph_drift_score, graph_drift_score_delta_vs_trailing, graph_drift_score_direction, leading_graph_drift_delta_vs_trailing_pp, mutation_scope_incomplete_rate
• counts: regression_count, `threshold_failure_coun