guard.config.example.json

{
  "//": "Copy to guard.config.json at your repo ROOT, then strip these //-comment keys (real JSON has no comments). Every path below is resolved relative to THIS repo (the consumer cwd), never the devkit package dir. Omit any field to keep its built-in default (see gate-engine/config.mjs DEFAULTS).",

  "//boundaries": "Cross-trust-boundary path prefixes. The decisions smell gate flags a single change that straddles 2+ of these (a cross-boundary move = likely an architectural decision). Default: [] (no boundaries → smell never fires).",
  "boundaries": ["src/main/", "socket-server/", "vercel-serverless/"],

  "//scanRoots": "Where the ratchets + structure scans look for implementation files. Default: ['src'].",
  "scanRoots": ["src", "socket-server/src", "vercel-serverless"],

  "//sourceExtensions": "Source extensions the ratchets count. Default: ['ts','tsx']. A JS/MJS codebase sets ['mjs','js']. Tests (*.test.<ext> / *.spec.<ext>) are excluded from impl fan-out but included when maxTestLines is enabled.",
  "sourceExtensions": ["ts", "tsx"],

  "//maxLines": "Raw line cap for implementation files. Existing oversized files are grandfathered shrink-only. 0 = off.",
  "maxLines": 500,

  "//maxTestLines": "Looser raw line cap for test files. Existing oversized tests are grandfathered shrink-only into the same size-lines.json baseline. 0 = off.",
  "maxTestLines": 2000,

  "//decisionsDir": "Append-only decision-log dir (guard-decisions CLI + smell gate target). Default: 'docs/decisions'.",
  "decisionsDir": "docs/decisions",

  "//fanoutCap": "Max non-test impl files per folder (any depth) before guard-fanout trips. Default: 12.",
  "fanoutCap": 12,

  "//fanoutExempt": "Flat-by-design folders exempt from the fanout cap (e.g. one-file-per-domain routers, vendored UI primitives). Default: [].",
  "fanoutExempt": ["src/main/lib/trpc/routers", "src/renderer/components/ui"],

  "//allowlistPath": "Co-occurrence intentional-dup approvals (guard-dup + guard-clone). Default: '.co-occurrence-allowlist.json'.",
  "allowlistPath": ".co-occurrence-allowlist.json",

  "//thresholds": "Matcher/clone tier + size knobs. Override any subset; unspecified knobs keep their default.",
  "thresholds": {
    "nearCode": 0.95,
    "driftCode": 0.8,
    "driftDesc": 0.88,
    "minLoc": 15,
    "minTokens": 50
  },

  "//indexPath": "search-code embedding index for the semantic duplication matcher. null (or omit) => matcher opts out / fails open; guard-clone + ratchets still run. OMITTING is not the same as writing null: `devkit doctor` reports drift when the key is ABSENT while .search-code/index.db exists (or search-code was selected at init), because that combination is devkit's own wiring lost rather than a choice. An explicit null is the DECLARED opt-out and is always silent. Env: GUARD_INDEX_PATH (or SEARCH_CODE_DB, matcher-only).",
  "indexPath": ".search-code/index.db",

  "//searchTool": "Semantic-search tool NAME the search-steering hooks point agents at. Default: 'mcp__codebase__searchCode'. Env override: GUARD_SEARCH_TOOL.",
  "searchTool": "mcp__codebase__searchCode",

  "//graphTool": "Graph/dependency tool NAME the search-steering hooks point agents at. Default: 'graphify'. Env override: GUARD_GRAPH_TOOL.",
  "graphTool": "graphify",

  "//testCommand": "Test command the testing agents run (e.g. 'bun run test:run'). Default: null => agents fall back to the package.json test script. Env override: GUARD_TEST_COMMAND.",
  "testCommand": null,

  "//coverage": "The `coverage` guard (opt-in — add it to your devkit guards). Reads coverage/coverage-final.json (produced by `test:run:coverage`) and enforces the threshold KEYS you set here (statements/functions/lines/branches — any subset). FAIL-CLOSED: when the guard is selected and coverage data is ABSENT, the commit fails hard (run test:run:coverage first). Set `false` to bypass entirely. Default (omit): {} = enforce no % floor but still fail hard on absent data.",
  "coverage": { "statements": 60, "functions": 55 },

  "//review": "Topology the reviewer subagents read. backendRoots/frontendRoots = path prefixes per reviewer. An EMPTY array disables that domain's reviewers entirely \u2014 \"frontendRoots\": [] means frontend-security-reviewer and frontend-performance-reviewer are never selected (the gate warns on stderr when a commit stages frontend files anyway; `devkit doctor` flags it against the detected stack). trustBoundaries = optional prose describing your client/server split. shortcutTracking = enable the tracked-story rule. accessibility.skipTouchTargets = opt out of the 44px WCAG touch-target check (e.g. a desktop-only app).",
  "review": {
    "backendRoots": ["src/main", "socket-server", "vercel-serverless"],
    "frontendRoots": ["src/renderer", "src/preload"],
    "trustBoundaries": "src/main = untrusted client; socket-server + vercel-serverless = trusted backend",
    "shortcutTracking": false,
    "accessibility": { "skipTouchTargets": true }
  }
}