| name | scan-for-defects-semantic |
| description | Run the deep, semantic subset of the multi-pass defect scan — bugs that need contracts and protocols context to spot. Run after protocols, before porting. Covers concurrency and resource management, security and trust boundaries, and API contract violations (including state machine drift). The mechanical subset (logic, error handling, config) runs earlier in the `defect-scan-mechanical` phase, after architecture. |
Scan For Defects — Semantic Pass
This phase runs the deep, semantic half of the defect-scan methodology. The findings here only become legible once you know what the code is supposed to do — that is what the contracts and protocols phases give you. The early mechanical bugs (passes 1, 2, 6) were caught in the earlier defect-scan-mechanical phase.
The source code to analyze is in the parent directory (../ relative to .codecarto/).
Prerequisites
Required:
findings/architecture/architecture-map.mdfindings/contracts/behavioral-contracts.md — pass 5 needs this to define "violation."findings/protocols/protocols-and-state.md — passes 3 and 5 need this for state machine and event-ordering analysis.findings/defect-scan-mechanical/mechanical-defects.md — read so you do not re-flag what the mechanical phase already covered.
If any prerequisite is missing, stop and surface the gap. The semantic pass is the paid-for benefit of running the mechanical phase early; do not regress it by running the semantic pass blind.
Pass Execution Order
Run these three passes sequentially. Read the pass file, scan the source, record findings, then move to the next pass. Each pass file is reused from the legacy defect-scan phase.
| Pass | File | Focus |
|---|
| 3 | findings/defect-scan/passes/03-concurrency-and-resources.md | Race conditions, lock issues, async pitfalls, resource leaks |
| 4 | findings/defect-scan/passes/04-security-and-trust.md | Input validation, auth gaps, secrets in code, trust boundaries |
| 5 | findings/defect-scan/passes/05-api-contract-violations.md | Spec vs. implementation drift, return type mismatches, state machine violations |
Prioritization
Use the contracts and protocols outputs to decide emphasis:
- No concurrency model in protocols? Skim pass 3, focus elsewhere.
- No auth system in contracts? Skip the auth sections of pass 4, still check input validation.
- Heavy state machine in protocols? Spend extra time on pass 5.
- Many features in contracts marked "core" or "important"? Pass 5 spec-vs-impl drift on those is high-value.
Evidence, Severity, and Action Classification
Use the scheme from findings/defect-scan/SKILL.md. The severity and action sets are the same as the legacy defect-scan phase.
When citing a contract or protocol violation, include the contract ID or state-machine reference from the upstream finding so the porting phase can trace the chain.
Honor the carry_forward routing
Read the carry_forward entries in workflow/status.yaml whose target_phase is defect-scan-semantic. The mechanical phase may have routed semantic-flavored sightings here for closure.
Output
Write findings to the primary output using templates/semantic-defects.md. Organize by pass, then by severity within each pass. End with a summary table covering only passes 3, 4, and 5.
The porting phase's reverse-engineering bundle has a "Defect Synthesis" section that consolidates this report and the mechanical report — do not pre-fill that here.
