Configuration

.code-scalpel Directory Guide

What appears after uvx codescalpel init, what each file does, and how to configure it for your project and tier.

1) What init creates

Running uvx codescalpel init scaffolds a governance-ready .code-scalpel/ directory:

  • policy.yaml + policy.manifest.json — Security rules and integrity manifest (OPA/Rego backed).
  • budget.yaml — Change budget (files/lines per session).
  • config.json — Governance profile, protected paths, enforcement mode, audit settings.
  • dev-governance.yaml — Development guardrails (docs/tests/architecture hygiene).
  • project-structure.yaml — Expected layout for core modules, tests, docs, configs.
  • ide-extension.json — IDE governance toggle; logs saves to .code-scalpel/audit.jsonl.
  • policies/ — Starter Rego packs (architecture, devops, devsecops, project).
  • license/README.md — Where to place license.jwt for Pro/Enterprise.
  • .gitignore, README.md, HOOKS_README.md, .env.example, .env — Manifest secret lives in .env; keep it out of git.
  • audit.log — Placeholder for runtime audit trail (gitignored).
Secrets

.env includes SCALPEL_MANIFEST_SECRET for policy integrity. Copy to CI/CD secrets, keep .env untracked.

2) Configure the key files

  • policy.yaml: Toggle SQLi/XSS/command/path protections; wire in specific Rego policies from policies/; choose warn or block.
  • budget.yaml: Set max files/lines per session to control blast radius.
  • config.json: Pick enforcement mode, protected paths, and audit logging; enable integrity verification on startup.
  • dev-governance.yaml: Require READMEs for new modules, tests before merge, and architecture boundary checks.
  • project-structure.yaml: Declare expected locations for core modules, tests, docs, CI, and Dockerfiles.
  • ide-extension.json: Turn on IDE governance and send audit events to .code-scalpel/audit.jsonl.
  • policy.manifest.json: Generated on init; keep in git to detect tampering.
  • license/: Drop license.jwt here for Pro/Enterprise features.

3) Tiers, features, and limits

Tier and feature enforcement comes from the core tooling and your governance settings. Use:

  • Environment: CODE_SCALPEL_TIER=community|pro|enterprise when starting the MCP server.
  • Capabilities: uvx codescalpel capabilities --tier <tier> (requires a limits file if you add one).
  • Tool pages: See individual tool pages for behavior by tier and default limits.

4) Next steps

  1. Edit policy.yaml and budget.yaml for your org.
  2. Set config.json enforcement to block for production.
  3. Add your license.jwt to .code-scalpel/license/ (Pro/Enterprise).
  4. Commit non-secret config files; keep .env and audit* out of git.