StepCheck Dev

Live: 126-session audit receipt · 50-turn interactive replay

Deterministic Anti-Context-Rot State Engine · BYOK Token-Firewall Proxy · Streamable HTTP MCP Server · Split-Pane Visual Workspace. Ubiquitous language and the two public testing seams live in GLOSSARY.md.

Layout

Run (turnkey)

pipx install git+https://github.com/lalithasutam/stepcheck-dev   # the `stepcheck` CLI, no clone needed
pip install -e .            # …or from a clone (editable)
(cd frontend && npm install && npm run build)   # once: compiled Studio served at /studio
stepcheck up                # one port (:8420): Studio UI + Door 1 proxy + REST + MCP + WS
stepcheck benchmark         # 50-turn coding-rot benchmark
stepcheck review            # architecture-review.html
stepcheck preview           # stepcheck-studio-preview.html (self-contained replay)
stepcheck audit             # your own cache-cliff waste + Read-tool bloat, no server needed → stepcheck-audit.html
stepcheck ci backend        # headless gate: parse + attestations + Gates A/B/C for every module (CI/PR)
stepcheck llms              # docs/llms.txt + docs/llms-full.txt from README, GLOSSARY, LAUNCH and benchmarks/results.json
stepcheck hooks             # .claude/hooks + settings wiring: Read over threshold -> skeleton, Edit of a locked module -> deny, Stop while dirty -> block
stepcheck ci . --report     # the headless gate plus a Markdown PR checklist: touched modules, re-verified callers, conserved symbols, in-toto digests
stepcheck audit --card      # stepcheck-audit-card.svg + a copy-paste badge line; file names and session ids never appear

Door 1: accordion compaction and tier routing

Every proxied turn through /v1/messages or /v1/chat/completions passes a three-band compactor: the last four messages stay verbatim, older Python source blocks over 150 tokens are replaced in place by their AST skeleton, dead-end turns are pruned, and after a cache-cliff gap the oldest band folds into one OKF session-state frame. The dry-run response carries a stepcheck.compaction block with per-band token counts. Routing is opt-in: x-stepcheck-tier: auto (or STEPCHECK_TIER_POLICY=auto) sends a focused single-symbol turn to STEPCHECK_FAST_MODEL first and re-sends it to the requested frontier model only when a gate rejects the draft; without the header nothing changes.

TypeScript and JavaScript projects

.ts, .tsx, .js and .jsx files are indexed next to .py (declaration files, node_modules, dist, build and out are skipped). Relative imports become graph edges, top-level declarations render as brace-elided skeletons, patch ops splice exact line spans, and Gates A/B plus the DSSE attestation apply unchanged; Gate C has no invariants for TypeScript yet, and class members are not individually addressable.

Checkouts and patch ops address methods too: focus=["StateKernel.commit"] emits that one method verbatim inside a class skeleton, and replace_symbol / delete_symbol on "Class.method" splice only its lines. A name always addresses its whole definition group (@overload stubs + implementation, a @property with its setter). StateKernel.provenance(session_id, node_id) exports the latest attestation as an in-toto Statement v1 inside a DSSE envelope (application/vnd.in-toto+json), the shape cosign and Witness consume; the signature is the kernel's deterministic SHA-256 scheme, not a key.

Claude Code slash commands (work out of the box after cloning)

.claude/commands/ ships four project commands. They need the gateway running (stepcheck up) and the stepcheck MCP server connected (claude mcp add --transport http stepcheck http://127.0.0.1:8420/mcp/); CLAUDE.md supplies the rules they enforce.

Run (development)

# backend + tests
cd backend && pip install -r requirements.txt && python -m pytest -q
python server.py                         # gateway on :8420 (PORT overrides)

# frontend
cd frontend && npm install && npm run dev   # Studio on :5173
# open http://localhost:5173/?session=<session_id from POST /v1/step/init>

# benchmark + report
python3 benchmarks/coding_rot_benchmark.py
python3 benchmarks/generate_review.py

# extension (compile check; load the folder via VS Code "Run Extension")
cd extension && npm install && npm run compile

Door 1 in one call

SID=$(curl -s localhost:8420/v1/step/init -d '{"project_root":"/path/to/project"}' \
      -H 'content-type: application/json' | jq -r .session_id)
curl -s localhost:8420/v1/messages \
  -H "x-stepcheck-session: $SID" -H "x-stepcheck-node: billing" \
  -H 'content-type: application/json' \
  -d '{"model":"claude-sonnet-4-5","max_tokens":512,"messages":[...]}'
# add x-api-key + x-stepcheck-upstream (or STEPCHECK_UPSTREAM_BASE) to forward BYOK;
# without them you get the deterministic dry-run with stepcheck.sent_messages.

Testing rules (skill precedence)

tdd + codebase-design override python-testing-patterns on mocking: never mock internal modules, AST parsers, YAML validators, or hash functions. Tests hit Seam 1 / Seam 2 only, against concrete non-tautological fixtures (hand-written projects, hand-calculated telemetry numbers).

Security model

Gate C exec-loads the agent's staged module in an isolated namespace under a step/time guard so callable invariants can run against it. That is an isolated namespace, not a security sandbox: run the gateway in a container when the agent is untrusted. Python projects only for now.

License

Apache-2.0 — see LICENSE and NOTICE. Everything in this repository is the open core (kernel, gates, MCP server, BYOK proxy, Studio, stepcheck ci and stepcheck audit). If StepCheck gets real use, the paid product will be a team layer (shared attestation ledger, org-wide CI gate); the core stays open.