session-orchestrator 3.16.0

package/skills/discovery/probes-arch.md

@@ -0,0 +1,252 @@
+> See probes-intro.md for confidence scoring reference.
+
+## Category: `arch`
+
+### Probe: circular-dependencies
+
+**Activation:** Any project with import/require statements.
+
+**Detection Method:**
+
+**Preferred (language-mapper-supported projects):**
+
+Call `extractSemanticSlices(filePath, { type: 'imports' })` from `scripts/lib/language-mappers/index.mjs` for each source file to obtain a typed list of import edges. The mapper handles TypeScript, JavaScript, and Markdown files natively; unsupported file types return an empty array (graceful degradation). Feed the resulting `{source_file -> [imported_file]}` adjacency map directly into the cycle-detection loop below.
+
+```js
+// Pseudocode — wire once per probe run
+import { extractSemanticSlices } from '$PLUGIN_ROOT/scripts/lib/language-mappers/index.mjs';
+
+for (const filePath of sourceFiles) {
+  const imports = await extractSemanticSlices(filePath, { type: 'imports' });
+  for (const { resolved } of imports) {
+    adjacency.get(filePath).push(resolved);
+  }
+}
+```
+
+**Fallback (when language-mapper returns empty or for unsupported file types):**
+
+```bash
+# Build import graph from source files
+# Step 1: Extract all import relationships
+Grep pattern: (import\s+.*from\s+["']([^"']+)["']|require\s*\(\s*["']([^"']+)["']\s*\))
+  --glob "*.{ts,tsx,js,jsx}" --glob "!**/node_modules/**"
+
+# Step 2: Resolve relative paths to absolute
+# Step 3: Build adjacency list
+
+# Alternative for Node.js projects with madge installed:
+npx madge --circular --extensions ts,tsx,js,jsx src/ 2>/dev/null
+```
+
+Algorithm (cycle detection — same for both paths above):
+1. Build `{source_file -> [imported_file]}` adjacency map
+2. Resolve relative imports to absolute paths
+3. For each file, BFS through imports with depth limit of 10
+4. If BFS revisits the starting file, record the cycle path
+
+**Evidence Format:**
+```
+Cycle: <file_a> -> <file_b> -> ... -> <file_a>
+Length: <number of files in cycle>
+Files Involved:
+  - <file_path_1>
+  - <file_path_2>
+```
+
+**Default Severity:** High.
+
+---
+
+### Probe: complexity-hotspots
+
+**Activation:** Any project with source files.
+
+**Detection Method:**
+
+```bash
+# Long functions (>50 lines)
+# Count lines between function declarations and closing braces
+# Heuristic: find function starts and measure to next function or file end
+Grep pattern: (function\s+\w+|const\s+\w+\s*=\s*(async\s+)?\([^)]*\)\s*=>|def\s+\w+|func\s+\w+)
+  --glob "*.{ts,tsx,js,jsx,py,go,rs}"
+
+# Deep nesting (>4 levels)
+# Count leading whitespace indicating nesting depth
+# For standard 2-space indent: >8 spaces = >4 levels
+# For standard 4-space indent: >16 spaces = >4 levels
+Grep pattern: ^(\s{16,}|\t{4,})\S
+  --glob "*.{ts,tsx,js,jsx,py,go,rs}"
+
+# Large files (>500 lines)
+wc -l src/**/*.{ts,tsx,js,jsx,py,go,rs} 2>/dev/null | awk '$1 > 500 {print $0}'
+
+# Functions with >5 parameters
+Grep pattern: (function\s+\w+|def\s+\w+|func\s+\w+)\s*\([^)]*,[^)]*,[^)]*,[^)]*,[^)]*,
+  --glob "*.{ts,tsx,js,jsx,py,go,rs}"
+```
+
+**Evidence Format:**
+```
+File: <path> Line: <n>
+Hotspot: long-function | deep-nesting | large-file | many-parameters
+Metric: <measured_value> (e.g., "73 lines", "6 levels", "612 lines", "8 params")
+Threshold: <threshold_value>
+```
+
+**Default Severity:** Medium.
+
+---
+
+### Probe: dependency-security
+
+**Activation:** Package manager detected (`package.json`, `requirements.txt`, `Pipfile`, `Cargo.toml`, `go.mod`).
+
+**Detection Method:**
+
+```bash
+# Node.js
+npm audit --json 2>/dev/null
+
+# Python
+pip-audit --format json 2>/dev/null
+
+# Rust
+cargo audit --json 2>/dev/null
+
+# Go
+govulncheck ./... 2>/dev/null
+```
+
+Parse JSON output for vulnerabilities. Focus on:
+- Critical severity CVEs
+- High severity CVEs
+- Vulnerabilities with known exploits
+
+**Evidence Format:**
+```
+Package: <name>
+Version: <installed_version>
+CVE: <CVE-ID>
+Severity: critical | high | medium | low
+Title: <vulnerability title>
+Fix Available: <fixed_version or NONE>
+```
+
+**Default Severity:** Critical (critical CVEs), High (high CVEs).
+
+---
+
+### Probe: architectural-friction
+
+**Activation:** Any project with TypeScript, JavaScript, Python, Go, or Rust source files. Targets structural design issues — shallow modules, pass-through adapters, and hypothetical seams — that indicate low leverage and poor locality in the codebase's interface design.
+
+**Detection Method:**
+
+Three heuristics are applied independently. Each produces its own findings.
+
+---
+
+**Heuristic A: shallow-module**
+
+A module exposes a large interface relative to its implementation size — it is a pass-through with little leverage. Callers pay the full interface cost but get minimal depth in return.
+
+```bash
+# Step 1: Count exported symbols per file (TypeScript/JavaScript)
+Grep pattern: ^\s*export\s+(default\s+)?(function|const|class|interface|type|enum)\s+\w+
+  --glob "*.{ts,tsx,js,jsx}"
+
+# Step 1b: Count exported symbols (Python)
+Grep pattern: ^def\s+\w+
+  --glob "*.py"
+
+# Step 1c: Count exported symbols (Go)
+Grep pattern: ^func\s+[A-Z]\w+
+  --glob "*.go"
+
+# Step 1d: Count exported symbols (Rust)
+Grep pattern: ^pub fn\s+\w+|^pub struct\s+\w+|^pub enum\s+\w+|^pub trait\s+\w+
+  --glob "*.rs"
+
+# Step 2: Count non-comment, non-blank implementation lines (LOC approximation)
+grep -cvE '^\s*(//|#|/\*|\*|$)' <file>
+
+# Flag condition: (exported_symbols / LOC) >= 0.5  AND  exported_symbols >= 3
+# The exported_symbols >= 3 guard avoids false positives on single-export utility files.
+```
+
+---
+
+**Heuristic B: pass-through-adapter**
+
+A class or module where most methods are 1–2 line delegations to a single dependency — it adds no leverage. The deletion test (LANGUAGE.md) reveals the module hides nothing; complexity would be identical across callers if it were removed.
+
+```bash
+# Detect single-line delegation methods in TypeScript/JavaScript classes
+Grep pattern: ^\s+\w+\s*\([^)]*\)\s*\{\s*return\s+this\.\w+\.\w+\(.*\)\s*;?\s*\}
+  --glob "*.{ts,tsx,js,jsx}"
+
+# Detect single-line delegation methods in Python classes (two-line form)
+# Match def line followed by a return self.<dep>.<method>(...) line
+Grep pattern: ^\s+def\s+\w+\(self[^)]*\):\s*$
+  --glob "*.py"
+# Then verify next non-blank line matches: ^\s+return\s+self\.\w+\.\w+\(.*\)$
+
+# Flag condition: (delegation_methods / total_methods) >= 0.7  AND  total_methods >= 3
+# Count total_methods per file with:
+Grep pattern: ^\s+(public\s+|private\s+|protected\s+|async\s+)*\w+\s*\([^)]*\)\s*\{
+  --glob "*.{ts,tsx,js,jsx}"
+```
+
+---
+
+**Heuristic C: one-adapter-seam**
+
+A TypeScript `interface` or `abstract class` with exactly one concrete implementation — a hypothetical seam, not a real one (Ousterhout, LANGUAGE.md: "One adapter means a hypothetical seam. Two adapters means a real one."). The seam pays an interface-learning cost that no second adapter ever amortises.
+
+```bash
+# Step 1: Enumerate all interface and abstract class names in the codebase
+Grep pattern: ^(export\s+)?(interface|abstract\s+class)\s+(\w+)
+  --glob "*.{ts,tsx}"
+
+# Step 2: For each name <N> found, count concrete implementations
+grep -rE 'implements\s+\b<N>\b|extends\s+\b<N>\b' src/ --include="*.ts" --include="*.tsx" \
+  | grep -v 'abstract class'
+
+# Step 3: Count method signatures within the interface/abstract class body
+Grep pattern: ^\s+\w+\s*\([^)]*\)\s*[:;]
+  within the block following the interface/abstract class declaration
+
+# Flag condition: implementation_count == 1  AND  method_signature_count >= 2
+# The method_signature_count >= 2 guard avoids flagging trivial marker interfaces.
+
+# Batch approximation when AST tooling is unavailable:
+# Enumerate all interface names first, then:
+grep -rE 'implements\s+(InterfaceName1|InterfaceName2|...)' src/ \
+  --include="*.{ts,tsx}" | sort | uniq -c | awk '$1 == 1 {print $0}'
+```
+
+**Evidence Format:**
+
+```
+File: <file_path> Line: <line_number>
+Probe: architectural-friction
+Category: arch
+Severity: medium
+Pattern: shallow-module | pass-through-adapter | one-adapter-seam
+Matched text: <relevant snippet>
+Title: <short description — e.g. "Shallow module exposes 8 symbols across 16 LOC">
+Description: <2-3 lines on why this is friction, using LANGUAGE.md vocabulary —
+             reference depth, leverage, locality, seam, adapter as appropriate>
+Recommended fix: invoke the `architecture` skill on this cluster (see skills/architecture/SKILL.md)
+```
+
+For `shallow-module`: describe the interface-to-depth ratio and what leverage is missing.
+For `pass-through-adapter`: describe which dependency is being delegated to and what the module fails to hide.
+For `one-adapter-seam`: name the interface and its single implementation; note that the seam cost has no second adapter to amortise it.
+
+Severity may be raised to **High** when: a shallow module has `exported_symbols >= 10`; a pass-through adapter wraps a high-fan-out dependency (>5 dependents); or a one-adapter seam sits on a hot import path (imported by ≥10 files). Note the raise condition in the Description field — do not auto-promote.
+
+**Default Severity:** Medium.
+
+---

package/skills/discovery/probes-audit.md

@@ -0,0 +1,95 @@
+> See probes-intro.md for confidence scoring reference.
+
+## Category: `audit`
+
+### Probe: harness-audit
+
+**Activation:** `.orchestrator/bootstrap.lock` exists (always-on for session-orchestrator-integrated repos).
+
+**Detection Method:**
+
+```bash
+# Step 1: Verify the script exists; skip if missing
+test -f scripts/harness-audit.mjs || { echo "SKIPPED: harness-audit -- scripts/harness-audit.mjs not found"; exit 0; }
+
+# Step 2: Run the audit. Capture stdout (JSON) and stderr (human summary) separately;
+# the script writes the human summary to stderr and the JSON record to stdout.
+AUDIT_OUTPUT="$(node scripts/harness-audit.mjs 2>/tmp/audit_summary_stderr)"
+EXIT_CODE=$?
+
+# Step 3: Validate the output is parseable JSON
+echo "$AUDIT_OUTPUT" | node -e "
+try {
+  const data = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+  process.stdout.write(JSON.stringify(data));
+} catch(e) {
+  process.stderr.write('PARSE_ERROR: ' + e.message);
+  process.exit(1);
+}" 2>/tmp/audit_parse_err
+
+# If parse fails, report FAILED and stop
+# If EXIT_CODE != 0, report FAILED with stderr content and stop
+```
+
+The script writes the same record to `.orchestrator/metrics/audit.jsonl` automatically. The probe reads from stdout only; no additional persistence step is needed.
+
+**Severity Mapping (category-level):**
+
+Evaluate `score_0_10` for each entry in the `categories` array of the JSON output:
+
+| `score_0_10` range  | Action |
+|---------------------|--------|
+| `>= 7`              | Info only — record in `audit.jsonl`, **do NOT emit a discovery finding** |
+| `>= 5` and `< 7`    | Emit finding with severity `medium` |
+| `< 5`               | Emit finding with severity `high` |
+
+Apply this mapping **per category**, not per individual check.
+
+**Finding Emission (one finding per low-scoring category):**
+
+For each category whose `score_0_10 < 7`, emit one finding using the following field values:
+
+| Finding Field    | Value |
+|------------------|-------|
+| `probe`          | `harness-audit` |
+| `category`       | `audit` |
+| `severity`       | `high` if `score_0_10 < 5`, `medium` if `5 <= score_0_10 < 7` |
+| `title`          | `harness-audit: <category name> below threshold (<score_0_10>/10)` |
+| `file_path`      | `.orchestrator/metrics/audit.jsonl` |
+| `line_number`    | `0` (category-level finding — not tied to a single line) |
+| `matched_text`   | Composed from the category's failed checks — one line per failed check: `[<check_id>] <message>` |
+| `description`    | `Harness audit category "<category name>" scored <score_0_10>/10 (earned <earned_points>/<max_points> points). See failed checks for details.` |
+| `recommended_fix`| List each failed check with its `path` and `evidence` context: `<check_id>: <path> — <evidence>` |
+| `confidence`     | `90` |
+
+**Evidence Format:**
+```
+Audit Run: session_id=<session_id>  rubric_version=<rubric_version>  started_at=<started_at>
+Overall:   score=<overall_mean_0_10>/10  band=<overall_band>  checks=<checks_passed>/<checks_total>
+Repository: branch=<branch>  sha=<head_sha>
+
+Category: <name>
+  Score:  <score_0_10>/10  earned=<earned_points>/<max_points>  weight=<weight>
+  Failed checks:
+    - <check_id>  status=fail  points=<points>  path=<path>
+      evidence: <evidence>
+      message:  <message>
+```
+
+**Default Severity:** High if `score_0_10 < 5`; Medium if `5 <= score_0_10 < 7`.
+
+**Labels for auto-created issues:** `type:discovery`, `area:harness` (new label — add to VCS label set if absent), `priority:high` or `priority:medium` per severity, `status:ready`.
+
+**Skip Conditions:**
+
+- If `scripts/harness-audit.mjs` is missing → `SKIPPED: harness-audit -- scripts/harness-audit.mjs not found`
+- If the script exits with a non-zero code → `FAILED: harness-audit -- script exited <code>: <stderr excerpt>`
+- If stdout is not valid JSON → `FAILED: harness-audit -- invalid JSON in script output: <parse error>`
+
+A skip or failure here does NOT abort the rest of the discovery run. Continue with other probes.
+
+**Out of Scope:**
+
+This probe reports findings only. It does not attempt remediation or auto-fix. Issue creation follows the standard `/discovery` Phase 5/6 triage flow.
+
+---

package/skills/discovery/probes-code.md

@@ -0,0 +1,329 @@
+> See probes-intro.md for confidence scoring reference.
+
+## Category: `code`
+
+### Probe: hardcoded-values
+
+**Activation:** Any project with source files.
+
+**Detection Method:**
+
+1. Hardcoded secrets:
+```bash
+# Grep for hardcoded secrets in source files (exclude tests, .env, config examples)
+Grep pattern: (password|api_key|secret|token|api_secret)\s*[:=]\s*["'][^"']+["']
+  --glob "!*.test.*" --glob "!*.spec.*" --glob "!.env*" --glob "!*.example"
+  --glob "!*.sample" --glob "!**/test/**" --glob "!**/tests/**"
+  --glob "!**/fixtures/**" --glob "!**/mocks/**"
+```
+
+2. Hardcoded URLs:
+```bash
+# Grep for hardcoded URLs in source files (exclude docs, configs, tests)
+Grep pattern: https?://
+  --glob "*.{ts,tsx,js,jsx,py,go,rs,java}" --glob "!**/test/**" --glob "!**/tests/**"
+  --glob "!README*" --glob "!*.md" --glob "!*.config.*"
+```
+
+3. Magic numbers:
+```bash
+# Grep for magic numbers (numeric literals outside obvious contexts)
+Grep pattern: [^a-zA-Z_]\b\d{4,}\b(?!\s*[;,\])}])
+  --glob "*.{ts,tsx,js,jsx,py,go,rs,java}" --glob "!**/test/**"
+```
+
+**Evidence Format:**
+```
+File: <path> Line: <n>
+Match: <matched_text>
+Classification: secret | url | magic-number
+```
+
+**Default Severity:** Critical (secrets), High (URLs), Medium (magic numbers).
+
+---
+
+### Probe: orphaned-annotations
+
+**Activation:** Any project with source files.
+
+**Detection Method:**
+
+```bash
+# Grep for TODO/FIXME/HACK/XXX/TEMP/WORKAROUND annotations
+Grep pattern: (TODO|FIXME|HACK|XXX|TEMP|WORKAROUND)[\s:()\-]
+  --glob "*.{ts,tsx,js,jsx,py,go,rs,java,rb,swift,kt}"
+```
+
+For each match, check whether a corresponding VCS issue exists:
+```bash
+# Search for issue referencing the annotation text
+gh issue list --search "<annotation text>" --limit 5
+# or
+glab issue list --search "<annotation text>" --per-page 5
+```
+
+Flag annotations with no corresponding issue.
+
+**Evidence Format:**
+```
+File: <path> Line: <n>
+Annotation: <TODO|FIXME|HACK|...>
+Text: <annotation text>
+Linked Issue: <#IID or NONE>
+```
+
+**Default Severity:** Low (TODO), Medium (FIXME/HACK/XXX/TEMP/WORKAROUND).
+
+---
+
+### Probe: dead-code
+
+**Activation:** `package.json` exists (JS/TS projects).
+
+**Detection Method:**
+
+1. Unused exports:
+```bash
+# Find all export statements
+Grep pattern: export\s+(default\s+)?(function|class|const|let|var|type|interface|enum)\s+(\w+)
+  --glob "*.{ts,tsx,js,jsx}" --glob "!**/node_modules/**"
+
+# For each exported name, check for importers
+Grep pattern: import.*<exported_name>
+  --glob "*.{ts,tsx,js,jsx}" --glob "!**/node_modules/**"
+
+# Flag exports with 0 importers (exclude index files and entry points)
+# Exclude: index.ts, index.js, main.ts, main.js, app.ts, app.js
+```
+
+2. Unused dependencies:
+```bash
+# List all dependencies from package.json
+cat package.json | python3 -c "import json,sys; deps=json.load(sys.stdin).get('dependencies',{}); [print(d) for d in deps]"
+
+# For each dependency, check if it is imported anywhere
+Grep pattern: (import|require).*['"]<dependency_name>
+  --glob "*.{ts,tsx,js,jsx}" --glob "!**/node_modules/**"
+```
+
+**Evidence Format:**
+```
+Type: unused-export | unused-dependency
+Name: <export_name or dependency_name>
+Defined In: <file_path>:<line>
+Importers Found: 0
+```
+
+**Default Severity:** Low.
+
+---
+
+### Probe: ai-slop
+
+**Activation:** Any project with source files.
+
+**Detection Method:**
+
+1. Slop patterns (reference `slop-patterns.md` for full pattern list):
+```bash
+# Filler phrases in comments
+Grep pattern: (as you can see|it's worth noting|needless to say|it should be noted|obviously|of course|basically|essentially|simply|let's go ahead|let's proceed|moving on to)
+  --glob "*.{ts,tsx,js,jsx,py,go,rs,java}"
+
+# Over-documented trivial code (param docs repeating param name)
+Grep pattern: @param\s+(\w+)\s+[-—]\s*(the\s+)?\1
+  --glob "*.{ts,tsx,js,jsx}"
+
+# Generic error messages
+Grep pattern: catch.*throw new Error\(["'].*error occurred
+  --glob "*.{ts,tsx,js,jsx,py}"
+
+# Redundant type assertions
+Grep pattern: as string(?=\s*[;,)\]])
+  --glob "*.{ts,tsx}"
+```
+
+2. Hallucinated imports (verify every import resolves):
+```bash
+# Extract all relative imports and check they exist on disk
+Grep pattern: from\s+["'](\.\.?/[^"']+)["']
+  --glob "*.{ts,tsx,js,jsx}"
+
+# For each match, verify the file exists:
+# test -f <resolved_path>.ts || test -f <resolved_path>.tsx || test -f <resolved_path>/index.ts
+
+# Extract package imports and verify against package.json
+Grep pattern: from\s+["']([^./][^"']*)["']
+  --glob "*.{ts,tsx,js,jsx}"
+# Verify each package is in dependencies or devDependencies
+```
+
+**Evidence Format:**
+```
+Type: slop-pattern | hallucinated-import
+File: <path> Line: <n>
+Pattern: <matched_text>
+Category: filler | over-doc | generic-error | redundant | hallucinated
+```
+
+**Default Severity:** Medium (slop patterns), High (hallucinated imports).
+
+---
+
+### Probe: type-safety-gaps
+
+**Activation:** `tsconfig.json` exists.
+
+**Detection Method:**
+
+```bash
+# any type usage
+Grep pattern: :\s*any\b
+  --glob "*.{ts,tsx}" --glob "!*.test.*" --glob "!*.spec.*" --glob "!**/test/**"
+
+# Type assertion to any
+Grep pattern: as\s+any\b
+  --glob "*.{ts,tsx}" --glob "!*.test.*" --glob "!*.spec.*"
+
+# TypeScript directive suppressions
+Grep pattern: @ts-ignore|@ts-expect-error
+  --glob "*.{ts,tsx}"
+
+# Non-null assertions
+Grep pattern: \w+!\.
+  --glob "*.{ts,tsx}" --glob "!*.test.*" --glob "!*.spec.*"
+```
+
+**Evidence Format:**
+```
+File: <path> Line: <n>
+Pattern: any-type | as-any | ts-ignore | ts-expect-error | non-null-assertion
+Code: <matched_text>
+```
+
+**Default Severity:** Medium.
+
+---
+
+### Probe: test-coverage-gaps
+
+**Activation:** Test infrastructure exists (test directory, test config, or test files present).
+
+**Detection Method:**
+
+```bash
+# Find all source files
+Glob pattern: src/**/*.{ts,tsx,js,jsx,py,go,rs}
+  --glob "!*.test.*" --glob "!*.spec.*" --glob "!**/test/**" --glob "!**/tests/**"
+  --glob "!**/fixtures/**" --glob "!**/mocks/**" --glob "!**/__mocks__/**"
+
+# For each source file, check if a corresponding test file exists:
+# JS/TS: <name>.test.ts, <name>.spec.ts, <name>.test.tsx, <name>.spec.tsx
+# Python: test_<name>.py, <name>_test.py
+# Go: <name>_test.go
+# Rust: tests/<name>.rs or #[cfg(test)] in same file
+
+# List source files with no test counterpart
+```
+
+**Evidence Format:**
+```
+File: <path>
+Test File Expected: <expected_test_path>
+Status: MISSING
+```
+
+**Default Severity:** Medium.
+
+---
+
+### Probe: test-anti-patterns
+
+**Activation:** Test files exist.
+
+**Detection Method:**
+
+```bash
+# Tests with no assertions (assert-nothing)
+# Find test functions/blocks, check for expect/assert within them
+Grep pattern: (it|test)\s*\(
+  --glob "*.{test,spec}.{ts,tsx,js,jsx}"
+# Then verify each test block contains at least one:
+Grep pattern: (expect|assert|should|toBe|toEqual|toMatch|toThrow|toHaveBeenCalled)
+  # If absent in the same test block, flag as assert-nothing
+
+# Excessive mocking (test-the-mock)
+Grep pattern: (jest\.mock|vi\.mock|sinon\.stub|mock\()
+  --glob "*.{test,spec}.{ts,tsx,js,jsx}"
+# Flag files with >5 mock statements
+
+# Flaky test indicators
+Grep pattern: (setTimeout|sleep|delay|waitFor)\s*\(
+  --glob "*.{test,spec}.{ts,tsx,js,jsx}"
+
+# Snapshot abuse
+Grep pattern: toMatchSnapshot|toMatchInlineSnapshot
+  --glob "*.{test,spec}.{ts,tsx,js,jsx}"
+# Flag files with >10 snapshot assertions
+
+# Swallowed errors in tests
+Grep pattern: catch\s*\([^)]*\)\s*\{\s*\}
+  --glob "*.{test,spec}.{ts,tsx,js,jsx}"
+```
+
+**Evidence Format:**
+```
+File: <path> Line: <n>
+Anti-Pattern: assert-nothing | test-the-mock | flaky-indicator | snapshot-abuse | swallowed-error
+Code: <matched_text>
+```
+
+**Default Severity:** High.
+
+---
+
+### Probe: security-basics
+
+**Activation:** Any project with source files.
+
+**Detection Method:**
+
+```bash
+# eval usage
+Grep pattern: \beval\s*\(
+  --glob "*.{ts,tsx,js,jsx,py}" --glob "!**/node_modules/**"
+
+# Dangerous HTML injection (React)
+Grep pattern: dangerouslySetInnerHTML
+  --glob "*.{tsx,jsx}"
+
+# innerHTML assignment
+Grep pattern: innerHTML\s*=
+  --glob "*.{ts,tsx,js,jsx}"
+
+# SQL injection via template literals
+Grep pattern: `[^`]*SELECT[^`]*\$\{
+  --glob "*.{ts,tsx,js,jsx}" --glob "!**/test/**" --glob "!**/tests/**"
+
+# Permissive CORS
+Grep pattern: cors.*\*|Access-Control-Allow-Origin.*\*
+  --glob "*.{ts,tsx,js,jsx,py,go,java}" --glob "!**/test/**"
+
+# Insecure randomness in security contexts
+Grep pattern: Math\.random\(\)
+  --glob "*.{ts,tsx,js,jsx}" --glob "!**/test/**"
+# Cross-reference with nearby security-related terms (token, secret, key, auth, session)
+```
+
+**Evidence Format:**
+```
+File: <path> Line: <n>
+Vulnerability: eval | xss-dangerous | xss-innerhtml | sql-injection | cors-wildcard | insecure-random
+Code: <matched_text>
+Context: <surrounding lines>
+```
+
+**Default Severity:** High. Critical for SQL injection and XSS patterns.
+
+---