chore: add pre-commit config and fix terminology violations

Add .pre-commit-config.yaml matching edictum core setup:
- ruff (lint + format)
- check-terminology (enforce .docs-style-guide.md)

Terminology script adapted for console codebase:
- allowlist assignment rule `rule_id` (different concept from contract rules)
- allowlist network/SSRF "blocked" (infrastructure term, not verdict)
- scan .ts/.tsx files in dashboard/src/

Fix 8 terminology violations:
- "blocked" → "denied" in UI labels, test fixtures, comments
- "shadow mode" → "observe mode" in contract tooltips
- "Blocked endpoint" → "Denied endpoint" in contract template

Author: acartag7

.docs-style-guide.md

@@ -0,0 +1,88 @@
+# Edictum Docs Style & Terminology Guide
+
+This is the binding reference for all documentation writers. Every page must use these terms consistently.
+
+## Canonical Terms (USE THESE, NOT THE ALTERNATIVES)
+
+| Concept | Canonical Term | DO NOT USE |
+|---------|---------------|------------|
+| The YAML constructs that define rules | **contract** / **contracts** | policies, rules, guards, checks |
+| What Edictum does to tool calls | **enforces contracts** | governs, guards, protects, secures |
+| When a contract blocks a call | **denied** / **deny** | blocked, rejected, prevented, stopped |
+| When a contract allows a call | **allowed** / **allow** | passed, approved, permitted |
+| The runtime check sequence | **pipeline** | engine, evaluator, processor, middleware |
+| The sequence: preconditions -> execute -> postconditions -> audit | **pipeline** (describe the steps, don't rename them) | workflow, chain, flow |
+| What agents do that Edictum checks | **tool call** / **tool calls** | function call, action, operation, invocation |
+| The thin framework-specific integration layer | **adapter** / **adapters** | integration, plugin, connector, driver |
+| Shadow-testing without blocking | **observe mode** | shadow mode, dry run, passive mode, monitor mode |
+| The identity context on a tool call | **principal** | user, identity, caller, actor |
+| The structured output from postconditions | **finding** / **findings** | result, detection, alert, violation |
+| The YAML file containing contracts | **contract bundle** | policy file, rule file, config |
+| What Edictum IS | **runtime contract enforcement for agent tool calls** | governance framework, safety library, guardrails |
+
+## The One-Liner
+
+Use this exact framing (or close paraphrase) when describing what Edictum is:
+
+> Edictum enforces contracts on AI agent tool calls -- preconditions before execution, sandbox allowlists for file paths and commands, postconditions after, session limits across turns, and a full audit trail. Contracts are YAML. Enforcement is deterministic. The agent cannot bypass it.
+
+## The Core Metaphor
+
+Edictum sits at the **decision-to-action seam**. The agent decides to call a tool. Before that call executes, Edictum checks it against contracts. This is a hard boundary, not a suggestion.
+
+DO NOT use metaphors like: gatekeeper, guardian, shield, firewall, sentinel, watchdog.
+DO use: "hard boundary," "enforcement point," "the check between decision and action."
+
+## Writing Rules
+
+1. **Lead with the problem, then the solution.** Not "Edictum has X" but "Agents do Y bad thing. Edictum prevents this by..."
+2. **Show, don't describe.** Every concept page: working example within the first screen.
+3. **No marketing language.** No "powerful," "seamless," "revolutionary," "robust," "elegant." Just say what it does.
+4. **Short paragraphs.** 2-3 sentences max.
+5. **Code examples must be copy-pasteable.** If it doesn't work when pasted, delete it.
+6. **Deterministic, not probabilistic.** Emphasize that contracts are code, not suggestions. The LLM cannot talk its way past a contract.
+
+## Pipeline Description (USE THIS CONSISTENTLY)
+
+When describing what happens on every tool call:
+
+1. Agent decides to call a tool
+2. Edictum evaluates **preconditions** against the call's arguments and principal
+3. If any precondition fails: **deny** (call never executes)
+4. Edictum evaluates **sandbox contracts** against allowlist boundaries (file paths, commands, domains)
+5. If the call falls outside any sandbox boundary: **deny** or **pending_approval** (depending on `outside` setting)
+6. If all pass: tool executes
+7. Edictum evaluates **postconditions** against the tool's output
+8. Postcondition failures produce **findings**. With `effect: warn`, the tool result is unchanged. With `effect: redact` or `effect: deny`, the pipeline modifies the output for READ/PURE tools (WRITE/IRREVERSIBLE tools fall back to warn)
+9. **Audit event** is emitted for every evaluation (allowed, denied, or observed)
+
+Session limits (max calls, per-tool caps, attempt limits) are checked as part of steps 2-5.
+
+## What Edictum is NOT (be honest about these)
+
+- NOT prompt engineering or input guardrails (those filter what goes INTO the LLM)
+- NOT output content filtering (that filters what comes OUT of the LLM)
+- NOT an authentication/authorization system (it accepts a Principal but doesn't authenticate)
+- NOT ML-based detection (contracts are deterministic pattern matching)
+- NOT a proxy or network-level tool (it's an in-process library)
+
+## Page Structure Pattern
+
+Every page should follow:
+
+1. **Opening**: 1-2 sentences stating the problem this page addresses
+2. **Example**: Working code/YAML within the first visible screen
+3. **When to use this**: Concrete scenarios where this feature applies — real situations a user would recognize (e.g., "Your fintech agent needs to limit daily transaction approvals" not "This feature provides configurable limits"). Include:
+   - 2-4 concrete scenarios with brief descriptions
+   - Which user persona benefits (developer debugging vs. platform team in production)
+   - How this relates to other Edictum features (e.g., "Use callbacks for immediate reactions, OTel for historical dashboards")
+4. **Explanation**: How it works, why it matters
+5. **Reference**: Full details, edge cases, configuration
+6. **Next steps**: Links to related pages
+
+## Cross-Reference Conventions
+
+- Link to concepts pages for explanations: `[contracts](../concepts/contracts.md)`
+- Link to reference pages for syntax: `[YAML reference](../contracts/yaml-reference.md)`
+- Link to adapter pages by name: `[LangChain adapter](../adapters/langchain.md)`
+- Always use relative paths for internal links

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 89c421dff2e1026ba12cdb9ebd731f4a83aa8021  # v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: check-terminology
+        name: check-terminology
+        entry: python scripts/check-terminology.py
+        language: python
+        types_or: [python, markdown, yaml, json, ts, tsx]
+        pass_filenames: true

dashboard/src/pages/contracts/contract-detail.tsx

@@ -92,7 +92,7 @@ export function ContractDetail({ contract, coverage }: ContractDetailProps) {
             )}
             {contract.not_allows?.domains && (
               <>
-                <span className="font-medium text-muted-foreground">blocked</span>
+                <span className="font-medium text-muted-foreground">denied</span>
                 <span className="text-red-600 dark:text-red-400">{contract.not_allows.domains.join(", ")}</span>
               </>
             )}

dashboard/src/pages/contracts/contract-tooltips.tsx

@@ -63,7 +63,7 @@ export const EFFECT_TOOLTIPS: Record<string, { title: string; description: strin
   },
   observe: {
     title: "observe",
-    description: "Logs the event without blocking. Used for monitoring in shadow mode.",
+    description: "Logs the event without denying. Used for monitoring in observe mode.",
     href: `${DOCS}/contracts/effects#observe`,
   },
 }

dashboard/src/pages/contracts/templates.ts

@@ -43,7 +43,7 @@ contracts:
           - 'metadata\\.google\\.internal'
     then:
       effect: deny
-      message: "Blocked endpoint: {args.url}"
+      message: "Denied endpoint: {args.url}"
       tags: [security, ssrf]
 
   - id: pii-in-output

scripts/check-terminology.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Pre-commit hook: enforce .docs-style-guide.md terminology.
+
+Scans staged files for banned terms and reports violations.
+Exit 0 = clean, exit 1 = violations found.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+# Banned patterns: (regex, replacement hint, description)
+BANNED_PATTERNS: list[tuple[re.Pattern, str, str]] = [
+    (re.compile(r"\bshadow mode\b", re.IGNORECASE), "observe mode", "banned phrase"),
+    (re.compile(r"\bper-rule\b", re.IGNORECASE), "per-contract", "banned phrase"),
+    (re.compile(r"\bRuleResult\b"), "ContractResult", "old class name"),
+    (re.compile(r"\brule_id\b"), "contract_id", "old field name"),
+    (re.compile(r"\brule_type\b"), "contract_type", "old field name"),
+    (re.compile(r'"\brules_evaluated\b"'), '"contracts_evaluated"', "old field name"),
+    (re.compile(r"\bby rule\b", re.IGNORECASE), "by contract", "banned phrase"),
+    (re.compile(r"\bRules evaluated\b"), "Contracts evaluated", "banned CLI string"),
+    (re.compile(r"\ball rules passed\b", re.IGNORECASE), "all contracts passed", "banned CLI string"),
+]
+
+# "blocked" needs special handling — allow infrastructure/network uses
+BLOCKED_PATTERN = re.compile(r"\bblocked\b", re.IGNORECASE)
+BLOCKED_ALLOWLIST = {
+    # builtins.py loop variable: "for blocked in commands:"
+    "for blocked in commands",
+    "cmd == blocked",
+    "cmd.startswith(blocked",
+    # f-string references to the loop variable
+    "{blocked}",
+    # Network/SSRF security — "blocked address", "blocked network" is infra terminology
+    "blocked address",
+    "blocked network",
+    "blocked:",  # e.g. "Request to X blocked: resolves to Y"
+}
+
+# Files/dirs to skip
+SKIP_PATHS = {
+    ".docs-style-guide.md",
+    "scripts/check-terminology.py",
+    "CLAUDE.md",  # references banned terms when defining the enforcement rules
+}
+SKIP_DIRS = {
+    ".git",
+    "__pycache__",
+    ".ruff_cache",
+    "node_modules",
+    "dashboard/dist",
+}
+
+# Files where `rule_id` is legitimate — assignment rules are a different concept
+# from contract rules. `rule_id` here means "assignment rule ID", not "contract rule ID".
+RULE_ID_ALLOWLIST_PATHS = {
+    "assignment_rules",
+    "assignment_service",
+    "agent_registrations",
+    "test_agent_assignment",
+    "agents",  # dashboard API type includes assignment rule_id in agent response
+}
+
+# Only check these extensions
+CHECK_EXTENSIONS = {".py", ".md", ".yaml", ".yml", ".json", ".ts", ".tsx"}
+
+
+def should_skip(path: Path) -> bool:
+    path_str = str(path)
+    if path_str in SKIP_PATHS:
+        return True
+    for skip_dir in SKIP_DIRS:
+        if path_str.startswith(skip_dir):
+            return True
+    if path.suffix not in CHECK_EXTENSIONS:
+        return True
+    return False
+
+
+def check_file(path: Path) -> list[str]:
+    violations: list[str] = []
+    try:
+        lines = path.read_text().splitlines()
+    except (OSError, UnicodeDecodeError):
+        return []
+
+    is_changelog = path.name == "CHANGELOG.md"
+
+    for i, line in enumerate(lines, 1):
+        # Skip CHANGELOG lines that document renames (backtick-quoted old names)
+        if is_changelog and "`" in line and "→" in line:
+            continue
+
+        # Check banned patterns
+        for pattern, fix, desc in BANNED_PATTERNS:
+            if pattern.search(line):
+                # Allow rule_id in assignment rule files (different concept)
+                if fix == "contract_id" and any(
+                    a in path.stem for a in RULE_ID_ALLOWLIST_PATHS
+                ):
+                    continue
+                violations.append(f"  {path}:{i}: {desc} — use '{fix}' instead")
+                violations.append(f"    {line.strip()}")
+
+        # Check "blocked" with allowlist
+        if BLOCKED_PATTERN.search(line):
+            line_stripped = line.strip()
+            if not any(allowed in line_stripped for allowed in BLOCKED_ALLOWLIST):
+                violations.append(f"  {path}:{i}: 'blocked' — use 'denied' instead")
+                violations.append(f"    {line_stripped}")
+
+    return violations
+
+
+def main() -> int:
+    # If args are passed, check those files (pre-commit passes staged files)
+    # Otherwise, scan src/, tests/, dashboard/src/
+    if len(sys.argv) > 1:
+        files = [Path(f) for f in sys.argv[1:]]
+    else:
+        files = []
+        for directory in ["src", "tests", "dashboard/src"]:
+            d = Path(directory)
+            if d.exists():
+                files.extend(d.rglob("*"))
+        for extra in ["CHANGELOG.md", "README.md"]:
+            p = Path(extra)
+            if p.exists():
+                files.append(p)
+
+    all_violations: list[str] = []
+    for f in files:
+        if not f.is_file() or should_skip(f):
+            continue
+        violations = check_file(f)
+        all_violations.extend(violations)
+
+    if all_violations:
+        print("Terminology violations found (see .docs-style-guide.md):\n")
+        for v in all_violations:
+            print(v)
+        print(f"\n{len(all_violations) // 2} violation(s) found.")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/edictum_server/ai/system_prompt.py

@@ -78,7 +78,7 @@
     equals: production
 then:
   effect: deny
-  message: "Blocked: cannot email competitor domains in production"
+  message: "Denied: cannot email competitor domains in production"
 ```
 
 ### Pre-contract: Block all exec() calls

tests/test_adversarial/test_s1_session_bypass.py

@@ -119,7 +119,7 @@ async def test_tampered_session_payload(
     except Exception:
         # Server raised an unhandled error -- still means no access granted.
         # This is an implementation issue (should catch JSONDecodeError in
-        # authenticate), but from a security perspective the attacker is blocked.
+        # authenticate), but from a security perspective the attacker is denied.
         pass
 
 

tests/test_audit_fixes.py

@@ -29,7 +29,7 @@ def _make_event(call_id: str = "call-1", **overrides: object) -> dict:
         "verdict": "deny",
         "mode": "enforce",
         "timestamp": "2026-02-18T12:00:00Z",
-        "payload": {"reason": "blocked"},
+        "payload": {"reason": "denied"},
     }
     base.update(overrides)
     return base
@@ -249,7 +249,7 @@ async def test_stats_handles_null_decision_name(
         _make_event("no-decision", payload={"reason": "no contract"}, timestamp=now),
         _make_event(
             "with-decision",
-            payload={"decision_name": "test-contract", "reason": "blocked"},
+            payload={"decision_name": "test-contract", "reason": "denied"},
             timestamp=now,
         ),
     ]

tests/test_events.py

@@ -13,7 +13,7 @@ def _make_event(call_id: str = "call-1") -> dict:
         "verdict": "deny",
         "mode": "enforce",
         "timestamp": "2026-02-18T12:00:00Z",
-        "payload": {"reason": "blocked"},
+        "payload": {"reason": "denied"},
     }