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 |