gate-semantic

name	gate-semantic
description	Tiered semantic analysis of changed code (rg → ast-grep → OpenGrep). Detects error-path bugs structural gates miss. Findings default to WARN. Internal — invoked by verify.
allowed-tools	["Read","Bash","Glob","Grep","Write"]

Gate: Semantic Analysis

Goal

Detect semantic bugs in changed code using symbolic pre-processing when available. For each candidate finding, localize it explicitly with premises, claims, and conclusion grounded in file:line evidence.

Inputs

• config.json gates.semantic — categories, tools, optional rulesDir
• {repoStateRoot}/work/{selectedWork.id}/workflow.json — selected work unit
• Changed files via git diff --name-only $(git merge-base HEAD <baseBranch>)

Outputs

• {workDir}/evidence/semantic-report.md
• Gate status in the selected work's workflow.json

Constraints

Scope (MEDIUM freedom): Changed code files only. Skip markdown/JSON/YAML/config. No changed code → PASS.

Tool tiers (LOW freedom): Resolve from gates.semantic.tools config, fall back to PATH detection. Missing tools narrow scope — never FAIL or ERROR. Validate sg identity: sg --version 2>&1 | grep -iq 'ast-grep' (/usr/bin/sg from shadow-utils is a false positive).

Tier	Tool	Adds
0	rg	Text-pattern extraction + LLM
1	ast-grep (sg)	Structural JSON, metavariable capture
2	OpenGrep	Cross-function taint (rules: config rulesDir or .opengrep/rules/)

Extraction (HIGH freedom): Extract structural facts using highest available tier's tool. Feed facts (not raw files) to LLM. Tier 1: sg scan <file> --json --rule <rule> or sg run --pattern '...' <file> --json (avoid --stdin). Tier 2: opengrep scan --config <rules-dir> --json <file>.

Categories (LOW freedom):

Category	Tier	Diagnostic question
error-path-cleanup	0+	Does any error path skip releasing an acquired resource?
unchecked-errors	0+	Is any error-producing call's return value discarded?
fail-open-handling (CWE-636)	1+	Does any catch block swallow, broaden, or ignore errors?
error-data-leakage (CWE-209)	1+	Does any error response expose internals to the caller?
resource-lifecycle	2+	Is any acquired resource not released on all exit paths?

Categories requiring an unavailable tier are skipped with an INFO note. Sole owner of CWE-636 and CWE-209 analysis (transferred from gate-security to avoid duplicate findings).

Verdict (LOW freedom): Per protocols/evidence.md#verdict-rendering. All findings WARN by default. No findings = PASS. WARN-only = WARN. Any BLOCK = FAIL.

Tier 0 categories: permanently WARN-only. Tier 1+ may promote to BLOCK when: (1) ≥5 shipped units, (2) FP rate <10% per evidence.md#verdict-rendering calibration, (3) user opt-in via config {"severity": "block"}.

Evidence report: Tool availability, skipped categories with reason, each finding with category, file:line, tier/tool, severity, remediation.

Protocol References

• protocols/evidence.md#verdict-rendering -- verdict rendering and calibration
• protocols/evidence.md -- evidence storage
• protocols/state.md -- gate status updates
• protocols/context.md -- config and anchor doc loading

Failure Modes

Condition	Action
Disabled in config	sw-verify skips silently
No changed code files	PASS
No symbolic tools	Degrade to Tier 0
Tool missing at runtime	WARN, skip tier
No calibration data	All findings WARN