Skip to content

chore: add sentrux architectural gating#39

Merged
mattapperson merged 1 commit intomainfrom
chore/sentrux-setup
May 6, 2026
Merged

chore: add sentrux architectural gating#39
mattapperson merged 1 commit intomainfrom
chore/sentrux-setup

Conversation

@mattapperson
Copy link
Copy Markdown
Collaborator

Summary

  • Adds sentrux as the architectural quality sensor for this repo
  • Ships a starter .sentrux/rules.toml + baseline that match today's code
  • Wires a new structural-gate CI job that blocks PRs which regress structural metrics

What's in this PR

.mcp.json

Registers the sentrux MCP server at the repo root so any Claude Code session inside this checkout gets real-time structural feedback via MCP. Contributors need the sentrux binary installed locally (brew install sentrux/tap/sentrux or the Linux install script) for the MCP server to run.

.sentrux/rules.toml

Encodes the package's current layering:

inner-loop  →  lib  →  api-shape-helpers

Verified by reading imports: inner-loop/call-model.ts imports from lib/; lib/ files (anthropic-compat, claude-type-guards, stream-transformers) import from api-shape-helpers/; api-shape-helpers/ is a leaf.

Constraints: max_cycles=0, max_coupling="B", max_cc=15, no_god_files=true. Layer direction + three explicit boundary rules back up the layering.

⚠️ Layer order semantics in sentrux v0.5.7 are inverted relative to the public docs — order=0 is highest in the stack. This is documented inline in the rules file.

.sentrux/baseline.json

Snapshot of today's metrics (quality 5195, coupling 0.42, 1 cycle, 9 complex functions). sentrux gate compares against this; PRs that make any of these worse will fail CI.

.github/workflows/ci.yaml

New structural-gate job. Installs sentrux-linux-x86_64 v0.5.7 from GitHub Releases (pinned to the local version so baseline format stays aligned) and runs sentrux gate.

What this PR deliberately does NOT do

  • Doesn't fix the pre-existing cycle in src/lib/ (11 files in a strongly-connected component). sentrux check surfaces it; sentrux gate locks it at 1 so it can't grow. Fixing is follow-up work.
  • Doesn't fix the 9 functions over cc=15 (worst: convertToClaudeMessage at 25). Same rationale — gate prevents regression, refactor is separate.
  • Doesn't tighten max_coupling below B. Starter grade; tighten once we know the real coupling number and have taken one PR to adjust.

Test plan

  • sentrux check run locally — passes layer + boundary rules, fails on the pre-existing cycle and cc violations (expected, gate is the blocker not check)
  • sentrux gate run locally against committed baseline — ✓ No degradation detected
  • pnpm run lint && pnpm run typecheck pass on this branch
  • Verify the structural-gate CI job passes on this PR
  • Verify the job correctly fails if someone opens a follow-up PR that adds a new cycle or pushes a cc-25+ function (manual smoke test)

Follow-ups (not this PR)

  1. Open issue: break the cycle across src/lib/{async-params, conversation-state, item-types, model-result, next-turn-params, stop-conditions, stream-transformers, tool-context, tool-executor, tool-types, turn-context}.ts.
  2. Open issue: reduce cyclomatic complexity on the 9 functions listed by sentrux check.
  3. After (1) and (2) land, re-run sentrux gate --save to tighten the baseline, then raise max_coupling toward A.

Wire up sentrux via .mcp.json for Claude Code MCP integration and add
.sentrux/rules.toml encoding the inner-loop -> lib -> api-shape-helpers
layering. CI gains a structural-gate job that installs sentrux v0.5.7 and
runs `sentrux gate` against the saved baseline on every PR, blocking merges
that regress structural metrics (coupling, cycles, god files, complexity).
@mattapperson mattapperson merged commit 8ac64b5 into main May 6, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant