feat(decisions): gate hardening, decision tiers, RAG indexing, and test coverage

[laurentftech]

Summary

• Gate hardening: phantom bypass fix, approved_not_synced gate reason, --no-verify sentinel detection via post-commit hook
• Consolidation reliability: use IDs as traceability anchor to prevent duplicate decisions from LLM title variation; stable replaceDecisions fixes silent consolidation drop bug; merged decisions inherit earliest superseded recordedAt
• Decision scope tiers: DecisionScope = 'local' | 'component' | 'cross-domain' | 'system' — only cross-domain and system generate ADR files, preventing ADR spam from trivial implementation choices
• Scope classification:
  • Consolidation LLM prompt includes scope criteria with explicit negative rules
  • Extractor capped to local/component — cross-domain upgrade requires full multi-domain visibility and therefore only occurs during consolidation
  • Auto-promotion in record_decision uses two independent deterministic triggers: structural (files span 2+ distinct top-level dirs) OR semantic (multi-domain + contract keyword, not refactor)
• Gate violation taxonomy centralized: GATE_REASONS constant in constants.ts — all 4 reason codes shared by gate handler, docs, and tests
• Store/ADR sync invariant: purge only after all per-decision syncs complete; partial failure leaves decision at approved (safe to retry)
• Store lifecycle: purgeInactiveDecisions() — --sync always calls syncer so purge runs even with zero approved decisions (fixes early-exit skip)
• RAG indexing: ADR files indexed under domain "decisions" — search_specs and orient return relevant ADRs semantically
• Orient context: pending decisions surfaced by task domain/file relevance
• EMFILE fix on macOS: chokidar v5 + kqueue opened 28k+ file descriptors before evaluating glob patterns. Switched ignored from glob array to a string-segment function evaluated before FDs are opened — eliminates EMFILE on projects with large node_modules
• Replace better-sqlite3 with node:sqlite built-in: eliminates native addon compilation and GitHub prebuilt download at install time. Required for enterprise environments behind Nexus or other isolated registries. node:sqlite is built into Node.js 22.5+ — zero extra dependencies. Requires Node.js ≥ 22.5.0 (bumped from 20)
• CI bumped to Node 24 LTS: node:sqlite experimental warning is absent on Node 24+. Node 22 still works but prints the warning to stderr (suppress with NODE_NO_WARNINGS=1)
• MCP tool annotations: readOnlyHint/destructiveHint/idempotentHint added to all 45 tools — improves Claude Code Tool Search ranking so deferred tools surface faster on relevant queries
• MCP --minimal profile: spec-gen mcp --minimal exposes only 5 core tools (orient, search_code, record_decision, detect_changes, check_spec_drift). Pair with alwaysLoad: true in Claude Code .mcp.json for always-visible core tools; use the full server with alwaysLoad: false (default) for the remaining 40 deferred and searchable via Tool Search. Documented in docs/agent-setup.md
• orient() suggestedTools field: orient now returns a ranked list of relevant spec-gen tools derived from what it already knows (hub presence, spec domains, task keywords) — no extra I/O. Provides portable tool discovery for Cline/Cursor/OpenCode where Claude Code's Tool Search is unavailable
• +27 tests this session on scope gate, auto-promotion triggers, consolidator scope mapping, synced re-approval guard (+98 total vs base)

Decision scope tiers

local        — single file, no cross-cutting concern (refactors, extractions, renames)
component    — single component/service/module, no cross-boundary contract impact
cross-domain — touches multiple spec domains AND changes behavioral contracts  ← ADR written
system       — global architectural constraint (auth, infra, data model, API) ← ADR written

Scope promotion uses deterministic triggers that prevent LLM-only escalation paths — structural trigger (files span 2+ distinct top-level source dirs mapped to different inferred domains) OR semantic (multi-domain + contract keyword + not refactor). Extractor always outputs local/component; upgrade to cross-domain/system only at consolidation.

Old pending.json without scope → treated as component (no ADR). CLI --list shows scope badge: gray=local, blue=component, yellow=cross-domain, red=system.

node:sqlite migration notes

• Named params: { name: v } → { '@name': v }
• db.pragma() → db.exec('PRAGMA ...')
• db.transaction(fn)() → runTransaction(db, fn) helper using SAVEPOINT for nested transaction support
• .all() / .get() return Record<string, SQLOutputValue> — cast via as unknown as T
• Experimental warning: present on Node 22, absent on Node 24+. Not suppressed programmatically — process.emit/process.emitWarning monkeypatching is fragile and can mask legitimate warnings. Use NODE_NO_WARNINGS=1 on Node 22 if needed.

Two-server MCP config (token-efficient Claude Code setup)

{
  "mcpServers": {
    "spec-gen-core": {
      "type": "stdio",
      "command": "spec-gen",
      "args": ["mcp", "--minimal"],
      "alwaysLoad": true
    },
    "spec-gen": {
      "type": "stdio",
      "command": "spec-gen",
      "args": ["mcp"],
      "alwaysLoad": false
    }
  }
}

Core 5 always in context (~500 tokens). Full 45 deferred, searchable via Tool Search.

Test plan

• npm test — 2663 tests pass
• record_decision with local helper change → no ADR after sync (automated test)
• record_decision with cross-domain auth change → ADR created after sync (automated test)
• record_decision with 2 inferred domains + contract keyword → auto-promoted to cross-domain (automated test)
• record_decision with files in 2 different top-level dirs → auto-promoted to cross-domain (automated test)
• spec-gen decisions --list → scope badge visible (gray/blue/yellow/red manually verified)
• Old pending.json without scope field → loads cleanly, defaults to component (manually verified)
• git commit with approved-not-synced decisions → gate blocks with approved_not_synced reason (manually verified)
• git commit --no-verify → post-commit hook logs bypass warning (manually verified)
• spec-gen analyze on project with large node_modules → no EMFILE error on macOS (manually verified)
• npm install in isolated network (no GitHub access) → installs cleanly, no native compilation (node:sqlite built-in)
• Node 24 — no node:sqlite experimental warning (manually verified)
• Node 22 — experimental warning present but suppressed with NODE_NO_WARNINGS=1 (manually verified)
• spec-gen mcp --minimal → only 5 tools listed (manually verified via CLI help)
• orient("add payment method") → suggestedTools includes get_subgraph, get_spec, check_spec_drift (manually verified)

🤖 Generated with Claude Code

[clay-good]

Thank you @laurentftech ❤️