# FORGE-esm-require-guard

> ESM/CommonJS interop guard - blocks silent require() failure of .mjs modules at pre-commit. Foodset-derived from scar-001-esm-sct-silent-fail (2026-08-13). Static analysis, read-only.

- Skill: `ariffazil/forge-esm-require-guard` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ariffazil/forge-esm-require-guard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ariffazil/forge-esm-require-guard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: ariffazil (https://skillmd.com/u/ariffazil)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ariffazil/forge-esm-require-guard

---


# FORGE-esm-require-guard — ESM/CommonJS Interop Guard

> **Origin:** Scar scar-001-esm-sct-silent-fail (2026-08-13)
> **Type:** Foodset-derived skill (generated from failure, not authored from scratch)
> **Risk tier:** LOW (static analysis, read-only)
> **Autonomy tier:** T1 (auto-run in pre-commit)

## What This Skill Does

Detects `require()` calls in TypeScript/JavaScript files that belong to ESM packages (packages with `"type": "module"` in their package.json). This class of bug is **invisible to TypeScript type checking** because `require` is valid JavaScript — it just doesn't exist in ESM scope, and the failure is a runtime ReferenceError that gets swallowed by try/catch blocks.

## The Scar

The ESM SCT silent failure (2026-08-11 to 2026-08-13) cost the federation:
- 3 actors at FQ=0.00 for 3 days
- Entire s2 remediation pipeline blocked
- 5 of 8 remediation steps stalled
- Multiple sessions wasted debugging symptoms instead of cause

Root cause: `require("node:crypto")` in an ESM module, inside a try/catch that was designed for crypto errors, not module-system errors.

## Trigger Phrases

- "check ESM compatibility"
- "require in ESM"
- "CommonJS interop"
- "silent require failure"
- pre-commit hook for TypeScript packages

## The Procedure

### Step 1: Identify ESM packages

```bash
# Find all package.json files with "type": "module"
find /root -name package.json -exec grep -l '"type": "module"' {} \; 2>/dev/null
```

### Step 2: Scan for require() calls

```bash
# For each ESM package directory, scan .ts/.js files for require()
PACKAGE_DIR="<path>"
grep -rn 'require(' "$PACKAGE_DIR/src/" --include='*.ts' --include='*.js' | \
  grep -v node_modules | \
  grep -v '.d.ts' | \
  grep -v 'import.*require'
```

### Step 3: Classify findings

- **HARD FAIL:** `require("node:` or `require("crypto"` or `require("path"` etc. in ESM scope
- **WARN:** `require()` with a comment explaining why (rare legitimate use)
- **PASS:** No require() calls found

### Step 4: Report

```yaml
package: <name>
type: module
require_calls_found: <count>
findings:
  - file: <path>
    line: <number>
    severity: HARD_FAIL | WARN
    suggestion: "Use top-level import instead: import { X } from 'module'"
status: PASS | FAIL
```

## Test Fixture

```bash
#!/bin/bash
# test-esm-require-guard.sh
# Known-answer test: should DETECT require() in the pre-fix codebase,
# and PASS on the post-fix codebase.

TEST_DIR="${1:-/root/A-FORGE}"

# Check if package.json has type:module
if ! grep -q '"type": "module"' "$TEST_DIR/package.json" 2>/dev/null; then
  echo "SKIP: $TEST_DIR is not an ESM package"
  exit 0
fi

# Scan for require() in source files
HITS=$(grep -rn 'require("node:' "$TEST_DIR/src/" --include='*.ts' 2>/dev/null | \
  grep -v node_modules | grep -v '.d.ts')

if [ -n "$HITS" ]; then
  echo "FAIL: ESM package contains require() calls:"
  echo "$HITS"
  exit 1
else
  echo "PASS: No require() calls in ESM source"
  exit 0
fi
```

## Verification Result

```
Pre-fix  (before cb341202): FAIL — detected require("node:crypto") at sessionGate.ts:192
Post-fix (after cb341202):  PASS — clean
Independence:               known_answer (verified against both states)
```

## Anti-Fossilization

- **Review date:** 2026-11-13
- **Replay:** Run fixture against A-FORGE on every commit to src/
- **Deprecation condition:** If ESM spec changes to support require() (extremely unlikely), deprecate
- **Drift detection:** If new require() calls appear, the fixture catches them

## Origin Provenance

```
Scar: scar-001-esm-sct-silent-fail
Generated: 2026-08-13T00:30:00Z
Generated by: 333-AGI (OpenCode FI-001)
Verified by: known_answer test (independent of generator)
Promoted by: 333-AGI
Sovereign ratification: PENDING F13 (this is a candidate, not yet sealed to VAULT999)
```

This skill did not exist before the scar. It is foodset-derived.
Its existence proves the W1 wire is real.

DITEMPA BUKAN DIBERI — the first foodset-derived item. ⚒️