docs(governance): standardize documentation across polyrepo

- CLAUDE.md: repo-specific tech stack, commands, deps (points to root)
- LICENSE: MIT 2026 svrnty (standardized)
- CONTRIBUTING.md: unified workflow, correct co-author email
- SECURITY.md: unified vulnerability reporting policy
- CHANGELOG.md: Keep a Changelog template (if new)
- lefthook.yml: added doc-hygiene hook, improved bootstrap

Co-Authored-By: Svrnty Inc. <jp@svrnty.io>

CLAUDE.md

@@ -1,99 +1,47 @@
 # Development Guidelines
 
-Universal development practices for all Svrnty/a-gent repositories.
+> **Source of truth**: All engineering principles, commit rules, documentation standards, and governance policies are defined in the [root CLAUDE.md](../CLAUDE.md). This file contains repo-specific notes only.
 
-## Engineering Principles
+## Quick Reference
 
-### KISS (Keep It Simple)
+- **Branch**: `JP` for active development
-- Prefer straightforward control flow over clever meta-programming
+- **Commit format**: `type(scope): message`
-- Keep error paths obvious and localized
+- **Co-Author**: `Co-Authored-By: Svrnty Inc. <jp@svrnty.io>`
+- **Hooks**: `lefthook install` — enforces author, secrets, doc hygiene
+- **Docs required**: README.md, CHANGELOG.md, LICENSE, CONTRIBUTING.md, SECURITY.md
 
-### YAGNI (You Aren't Gonna Need It)
+## Tech Stack
-- Do not add features without concrete accepted use case
-- Do not introduce speculative abstractions
 
-### DRY + Rule of Three
+| Tool | Version |
-- Duplicate small logic when it preserves clarity
+|------|---------|
-- Extract shared utilities only after 3+ repeated patterns
+| C# | 14 |
+| .NET | 10.0 |
+| AOT | enabled (IsAotCompatible=true) |
+| Nullable | enabled |
 
-### SRP + ISP (Single Responsibility + Interface Segregation)
+## Commands
-- Keep each module focused on one concern
-- Avoid "god modules" mixing multiple responsibilities
 
-### Fail Fast + Explicit Errors
+| Command | Description |
-- Prefer explicit errors for unsupported states
+|---------|-------------|
-- Document fallback behavior when intentional
+| `dotnet build` | Build all 18 projects |
+| `dotnet test` | Run tests |
+| `dotnet format` | Format code |
 
-### Secure by Default
+## Key Dependencies
-- Deny-by-default for access boundaries
-- Never log secrets or sensitive payloads
 
-## Agent Workflow
+| Package | Description |
+|---------|-------------|
+| Svrnty.CQRS.Core | Core CQRS abstractions |
+| Svrnty.CQRS.DynamicQuery | Dynamic query support |
+| Svrnty.CQRS.gRPC | gRPC transport |
+| Svrnty.CQRS.Events | Event sourcing |
+| Svrnty.CQRS.Sagas | Saga orchestration |
+| Svrnty.CQRS.Notifications | Notification handlers |
+| Svrnty.CQRS.MinimalApi | Minimal API bindings |
 
-1. **Read before write** - Inspect existing code before editing
+## Repo-Specific Notes
-2. **Define scope** - One concern per PR
-3. **Implement minimal patch** - Apply KISS/YAGNI explicitly
-4. **Validate** - Run lint, format, test before commit
-5. **Document impact** - Note behavior changes and risks
 
-## Branch Strategy
+- Solution file: `Svrnty.CQRS.sln` with 18 projects.
-
+- Lint is handled by .NET analyzers — AOT compatibility and nullable reference types are enforced.
-- All repos use `JP` branch for active development
+- No Docker or proto files in this repo.
-- Always verify current branch before committing
+- Published under the `svrnty` org (git.openharbor.io/svrnty), not `a-gent`.
-
-## Commit Rules
-
-### Allowed Authors
-Only these emails are permitted for commits:
-- `jp@svrnty.io` (Jean-Philippe Brule)
-- `mathias@svrnty.io` (Mathias Beaulieu-Duncan)
-
-Configure with: `git config user.email jp@svrnty.io`
-
-### AI-Assisted Commits
-All AI-authored commits MUST include:
-```
-Co-Authored-By: Svrnty Inc. <jp@svrnty.io>
-```
-
-NEVER use third-party AI tool/company names in commits.
-
-### Git Hooks Setup
-Install lefthook to enforce commit standards:
-```bash
-brew install lefthook
-lefthook install
-```
-
-The hooks automatically:
-- Validate author email is in allowed list
-- Append Co-Authored-By footer
-- Warn on conventional commit format violations
-
-## PR Discipline
-
-- Clear, scoped commit messages
-- Small PRs preferred
-- Never commit personal/sensitive data
-- Reference related repos for cross-repo changes
-
-## Validation
-
-Run before every commit:
-- Format check (language-specific)
-- Lint check (language-specific)
-- Test suite
-
-## Anti-Patterns
-
-- Do NOT add heavy dependencies for minor convenience
-- Do NOT mix formatting-only with functional changes
-- Do NOT modify unrelated modules "while here"
-- Do NOT bypass failing checks without explanation
-
-## Cross-Repo Changes
-
-- Each repo is standalone with its own build configuration
-- Reference related repos in commit messages for cross-repo changes
-- Coordinate multi-repo changes via matching branch names
-- Test each repo independently before pushing

CONTRIBUTING.md

@@ -37,7 +37,7 @@ See [CLAUDE.md](./CLAUDE.md) for development practices, engineering principles,
 
    AI-authored commits must include:
    ```
-   Co-Authored-By: Svrnty Inc. <eng@svrnty.com>
+   Co-Authored-By: Svrnty Inc. <jp@svrnty.io>
    ```
 
 6. **Push & Create PR**

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Powered Softwares Inc.
+Copyright (c) 2026 svrnty
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

SECURITY.md

@@ -50,4 +50,3 @@ Security updates are provided for the latest release only.
 |---------|-----------|
 | Latest  | Yes       |
 | Older   | No        |
-

lefthook.yml

@@ -25,6 +25,25 @@ pre-commit:
           echo "WARNING: large files staged (>5MB):"
           echo "$LARGE"
         fi
+    doc-hygiene:
+      run: |
+        STAGED=$(git diff --cached --name-only)
+        # Check if code files are staged (not just docs)
+        CODE_CHANGED=$(echo "$STAGED" | grep -vE '\.(md|txt|yml|yaml|json|toml|lock)$|^LICENSE$|^\.gitignore$' || true)
+        if [ -z "$CODE_CHANGED" ]; then
+          exit 0
+        fi
+        # Warn if CHANGELOG.md is not being updated with code changes
+        if ! echo "$STAGED" | grep -q '^CHANGELOG.md$'; then
+          echo "WARNING: code changes staged without CHANGELOG.md update"
+          echo "  → Update CHANGELOG.md under [Unreleased] before committing"
+          echo "  → See root CLAUDE.md § Documentation Standards for format"
+        fi
+        # Warn if README.md is missing
+        if [ ! -f "README.md" ]; then
+          echo "WARNING: README.md is missing — every repo must have one"
+          echo "  → See root CLAUDE.md § README Requirements for structure"
+        fi
 
 commit-msg:
   commands:
@@ -36,6 +55,7 @@ commit-msg:
         fi
         if ! echo "$MSG" | head -1 | grep -qE '^[a-z]+(\([a-zA-Z0-9_-]+\))?: .+'; then
           echo "WARNING: commit message does not follow conventional format: type(scope): message"
+          echo "  → Types: feat, fix, refactor, docs, test, chore, ci, perf"
         fi
     append-coauthor:
       run: |
@@ -70,16 +90,24 @@ post-commit:
       run: |
         REPO_ROOT=$(git rev-parse --show-toplevel)
         HOOKS_DIR="$REPO_ROOT/../.svrnty-hooks"
+        [ -d "$HOOKS_DIR" ] || exit 0
         [ -f "$HOOKS_DIR/lefthook.yml" ] || exit 0
-        [ -f "$HOOKS_DIR/CLAUDE.md.template" ] || exit 0
         for sibling in "$REPO_ROOT"/../*/; do
           [ -d "$sibling/.git" ] || continue
           [ -f "$sibling/lefthook.yml" ] && continue
           SNAME=$(basename "$sibling")
+          # Deploy lefthook
           cp "$HOOKS_DIR/lefthook.yml" "$sibling/lefthook.yml"
-          cp "$HOOKS_DIR/CLAUDE.md.template" "$sibling/CLAUDE.md"
+          # Deploy CLAUDE.md
+          [ -f "$HOOKS_DIR/CLAUDE.md.template" ] && cp "$HOOKS_DIR/CLAUDE.md.template" "$sibling/CLAUDE.md"
+          # Deploy governance docs
+          [ -f "$HOOKS_DIR/LICENSE" ] && [ ! -f "$sibling/LICENSE" ] && cp "$HOOKS_DIR/LICENSE" "$sibling/LICENSE"
+          [ -f "$HOOKS_DIR/CONTRIBUTING.md" ] && [ ! -f "$sibling/CONTRIBUTING.md" ] && cp "$HOOKS_DIR/CONTRIBUTING.md" "$sibling/CONTRIBUTING.md"
+          [ -f "$HOOKS_DIR/SECURITY.md" ] && [ ! -f "$sibling/SECURITY.md" ] && cp "$HOOKS_DIR/SECURITY.md" "$sibling/SECURITY.md"
+          [ -f "$HOOKS_DIR/CHANGELOG.md.template" ] && [ ! -f "$sibling/CHANGELOG.md" ] && cp "$HOOKS_DIR/CHANGELOG.md.template" "$sibling/CHANGELOG.md"
+          # Install lefthook
           (cd "$sibling" && lefthook install 2>/dev/null)
-          echo "BOOTSTRAP: installed lefthook + CLAUDE.md in '$SNAME'"
+          echo "BOOTSTRAP: installed lefthook + governance docs in '$SNAME'"
         done
 
 pre-push: