SEMPTRACE — Structural Safety for AI-Written Python

What This Is

SEMPTRACE is not a formatter, linter, or IDE plugin.

It is a structural analysis layer that sits around human and AI coding workflows.

It answers questions like:

• Is this code structurally sound before I trust it?
• Did an AI change something it shouldn’t have?
• Where are the real execution boundaries, not just the visible ones?

What You Get

✅ Module 1 — Whitespace & Invisible Character Scanner

Detects:

• Tabs vs spaces
• Mixed indentation
• Trailing whitespace
• Zero-width / non-printing characters

These issues are silent, common, and frequently introduced by AI tools.

✅ Module 3a — Deterministic Nodules + Continuity Graph

• Segments Python code into structural nodules
• Builds a deterministic continuity graph (next / child / sibling / exit edges)
• No AST
• No heuristics
• Same input → same structure, every time

This is what makes SEMPTRACE usable as a governance layer, not just a checker.

✅ Minimal CLI (Terminal-First)

semptrace your_file.py
semptrace --json your_file.py

Designed to work:

• Locally
• In CI
• Alongside AI coding agents
• Without IDE lock-in

What This Is

Not

• ❌ Not a formatter (does not rewrite your code)
• ❌ Not a linter replacement
• ❌ Not an AI code generator
• ❌ Not a security scanner that promises “safe code”

SEMPTRACE reveals structure.

What you do with that visibility is up to you.

Why This Exists

AI coding tools are fast — but they:

• Don’t see invisible structure
• Drift indentation and scope
• Make large, confident changes that humans struggle to audit

SEMPTRACE gives you a shared structural truth between:

• Humans
• AI assistants
• CI pipelines

It’s a missing layer in modern coding workflows.

Who This Is For

• Developers using Claude / ChatGPT / Cursor / Copilot
• Vibe coders who want guardrails without complexity
• Teams reviewing AI-generated pull requests
• Anyone who has ever thought:

  “I think this code is fine… but I’m not 100% sure.”

Installation

unzip semptrace-core-v0.zip
cd semptrace-core
python -m venv .venv
source .venv/bin/activate
pip install -e .

Verify:

semptrace --help

Example Output

SEMPTRACE REPORT
============================================================
File: semptrace/scanner.py
Indent mode: spaces
Issues: 0 errors, 0 warnings
------------------------------------------------------------
Nodules: 62   Edges: 106

Design Principles

• Deterministic over clever
• Visibility over enforcement
• Human-readable over “AI magic”
• Works on existing codebases
• Safe to run anywhere

Roadmap (Non-Binding)

This is a v0 foundation.

Future modules may include:

• Structural diffs
• Guardrail enforcement
• CI integration
• AI steering layers

No promises. No subscriptions (yet).

This product stands on its own.

License & Use

• You may use this in personal, commercial, or internal projects
• No tracking
• No telemetry
• No network calls

Final Note

SEMPTRACE doesn’t try to replace your tools.

It gives you something most tools ignore:

Structural awareness in an AI-first coding world.