constitution

Defined in hooks/hooks.json

{
  "Stop": [
    {
      "hooks": [
        {
          "type": "prompt",
          "prompt": "You are validating constitution compliance before the session ends.\n\n## Your Task\n\nDetermine if the session should be allowed to stop or if constitution review is required.\n\n## Decision Logic\n\n### Step 1: Check for Constitution\n\nRun: `find . -maxdepth 3 -name \"CONSTITUTION.md\" 2>/dev/null | head -1`\n\nIf no output → **ALLOW STOP** (no constitution to enforce)\nIf found → Continue to Step 2\n\n### Step 2: Check Stop Hook Active Flag\n\nCheck conversation context for `stop_hook_active=true` flag.\n\nIf flag is true → **ALLOW STOP** (prevents infinite loop - reviewer already ran)\nIf flag is false/absent → Continue to Step 3\n\n### Step 3: Detect Changes\n\nRun: `git status --porcelain 2>/dev/null`\n\nIf no output AND no git repo → **ALLOW STOP** (no changes to validate)\nIf no output → Check last commit: `git diff --name-only HEAD HEAD~1 2>/dev/null`\nIf changes detected → Continue to Step 4\n\n### Step 4: Check if Doc-Only Changes\n\nFrom changes detected, check if all files are documentation:\n- .md files (except CONSTITUTION.md itself)\n- .txt files\n- Comment-only changes\n\nIf doc-only → **ALLOW STOP** (documentation doesn't need constitution review)\nIf code changes → Continue to Step 5\n\n### Step 5: Check if Review Was Performed\n\nSearch conversation history for:\n- \"constitution:reviewer\" skill invocation\n- \"constitution-review-report.md\" file creation\n- Recent agent invocation of \"constitution-reviewer\"\n\nIf review found in recent messages (last 10 turns) → **ALLOW STOP**\nIf no review found → Continue to Step 6\n\n### Step 6: Block and Suggest Review\n\n**BLOCK STOP** with this message:\n\n```\n⚠️  Constitution Compliance Check Required\n\nYour project has a CONSTITUTION.md but code changes haven't been validated.\n\n**Changes detected:**\n[List modified files from git status]\n\n**Required action:**\nRun constitution review before stopping:\n\n  Invoke the constitution:reviewer agent with --scope staged\n\nOr to bypass (not recommended):\n\n  Set stop_hook_active=true in context\n\n**Why this matters:**\nThe constitution defines non-negotiable project standards. Unvalidated changes may violate governance principles and cause issues later.\n```\n\n## Important Notes\n\n- **Always check stop_hook_active flag FIRST** (prevents infinite loops)\n- **Be conservative with blocking** (allow when uncertain)\n- **Provide clear next steps** (don't just block, tell user what to do)\n- **Respect git-less projects** (allow stop if no git)\n- **Doc changes are safe** (don't block for README updates)\n\n## Edge Cases\n\n**CONSTITUTION.md itself changed:** ALLOW (amendments update the constitution)\n**Only test files changed:** Still REQUIRE review (tests encode principles)\n**Git repo but no remote:** Still work (local validation is fine)\n**Reviewer ran but found CRITICAL violations:** Trust that reviewer reported them, ALLOW stop (user aware of issues)\n**Subagent invoked reviewer:** Count as valid review, ALLOW stop\n\n## Exit Codes\n\n- **ALLOW STOP:** Return success (empty output or \"✓ Constitution check passed\")\n- **BLOCK STOP:** Return failure with clear message showing why and what to do",
          "timeout": 30
        }
      ],
      "matcher": "*"
    }
  ],
  "SubagentStop": [
    {
      "hooks": [
        {
          "type": "prompt",
          "prompt": "You are validating if a subagent should be allowed to stop.\n\n## Your Task\n\nDetermine if this specific subagent should be allowed to complete.\n\n## Decision Logic\n\n### Step 1: Identify Subagent\n\nCheck context for subagent name/type.\n\n### Step 2: Special Case for Constitution Reviewer\n\nIf subagent is \"constitution-reviewer\" → **ALWAYS ALLOW STOP**\n\nReason: The reviewer is performing the validation that the Stop hook requires. If we block the reviewer, we create infinite loop.\n\n### Step 3: Check Constitution Exists\n\nRun: `find . -maxdepth 3 -name \"CONSTITUTION.md\" 2>/dev/null | head -1`\n\nIf no output → **ALLOW STOP** (no constitution to enforce)\nIf found → Continue to Step 4\n\n### Step 4: Apply Same Logic as Stop Hook\n\nUse simplified version of Stop hook logic:\n1. Check stop_hook_active flag → ALLOW if true\n2. Detect changes → ALLOW if none\n3. Check if doc-only → ALLOW if yes\n4. Otherwise → **ALLOW** (subagents are usually executing specific tasks)\n\n## Important Notes\n\n- **Never block constitution-reviewer subagent** (prevents infinite loop)\n- **Be permissive with subagents** (they're usually task-focused)\n- **Quick timeout** (10 seconds max - this is just safety check)\n\n## Exit\n\n- **ALLOW STOP:** Return success (\"✓ Subagent may complete\")\n- **BLOCK STOP:** Rare, only if clear violation",
          "timeout": 10
        }
      ],
      "matcher": "*"
    }
  ]
}

"Blocks Stop if CONSTITUTION.md exists with un-reviewed code changes. Uses git status/diff checks via prompt, searches history for prior review."