constitution-guardian

Constitution Guardian

Purpose

Enforce CC-DevFlow Constitution compliance by detecting violations in real-time during document editing, preventing non-compliant content from being saved.

Trigger: PreToolUse hook when editing devflow documents (PRD.md, EPIC.md, TASKS.md, TECH_DESIGN.md)

Enforcement Scope

Focus Articles (Real-time prevention):

• Article I.1: Quality First - No Partial Implementation
• Article III.1: Security First - No Hardcoded Secrets

Note: Full Constitution has 10 Articles. This guardrail focuses on the most critical real-time violations. Batch validation by validate-constitution.sh covers all Articles.

Violation Patterns

Article I.1: No Partial Implementation

Pattern 1: TODO placeholders

# ❌ BLOCKED
## User Stories
### US1: User Registration
TODO later: Add email verification flow
FIXME: Implement password strength validation

Regex Patterns:

• TODO.*later
• FIXME
• \[placeholder\]
• // TODO:.*later
• # FIXME:.*

Pattern 2: Simplified/Partial notes

# ❌ BLOCKED
## Implementation Notes
This is simplified for now, complete implementation would require...

Regex Pattern: simplified for now

Pattern 3: Version deferral

# ❌ BLOCKED
## Acceptance Criteria
- [ ] Basic login (v1)
- [ ] Remember me (defer to v2)

Regex Pattern: defer to v\d|will complete in v\d

Article III.1: No Hardcoded Secrets

Pattern 1: Environment variables with secrets

# ❌ BLOCKED
## Configuration
API_KEY=sk-abc123def456
JWT_SECRET=mysecretkey123
PASSWORD=admin123

Regex Patterns:

• API_KEY\s*=\s*['"]?[a-zA-Z0-9_-]{10,}
• SECRET\s*=\s*['"]?[a-zA-Z0-9_-]+
• PASSWORD\s*=\s*['"]?[^\s]+
• TOKEN\s*=\s*['"]?[a-zA-Z0-9_-]{10,}

Pattern 2: Code snippets with hardcoded secrets

// ❌ BLOCKED
const config = {
  apiKey: "sk-abc123def456",
  dbPassword: "postgres123"
};

Regex Patterns:

• apiKey:\s*['"][^'"]+['"]
• password:\s*['"][^'"]+['"]
• secret:\s*['"][^'"]+['"]

Blocking Message

When violation detected, PreToolUse hook returns exit code 2 (blocks file save):

⚠️ BLOCKED - Constitution Violation

Detected:
- [Line 42] TODO placeholder (Article I.1 - No Partial Implementation)
- [Line 58] Hardcoded API key (Article III.1 - No Hardcoded Secrets)

📋 ACTION:
1. Complete all TODOs/FIXMEs before saving
2. Move secrets to environment variables (.env, not committed)
3. Review `.claude/rules/project-constitution.md` v2.0.0
4. Run /flow-verify for comprehensive check

Source: Constitution Articles I.1, III.1
File: {file_path}

Constitutional Basis:
  Article I.1: "NO PARTIAL IMPLEMENTATION: Complete implementation or no implementation"
  Article III.1: "NO HARDCODED SECRETS: Use environment variables or secret management"

💡 SKIP: Add `@constitution-verified` comment or set SKIP_CONSTITUTION_CHECK=1

Constitutional Basis

Article I: Quality First

I.1 Complete Implementation Mandate:
  Prohibition: Any form of partial implementation or placeholder code
  Requirement: Complete implementation or no implementation
  Examples:
    ❌ Forbidden: "// TODO: Implement this later"
    ❌ Forbidden: "// Simplified for now, will complete in v2"
    ✅ Required: Fully functional, production-ready code

Enforcement:

• Generation time: prd-writer, tech-architect, planner agents check output
• Edit time: constitution-guardian guardrail blocks save (this skill)
• Phase completion: validate-constitution.sh batch validation

Article III: Security First

III.1 No Hardcoded Secrets:
  Prohibited:
    ❌ API_KEY = "sk-abc123..." in source code
    ❌ PASSWORD = "admin123" in config files
    ❌ JWT_SECRET embedded in code

  Required:
    ✅ Environment variables (.env files, not committed)
    ✅ Secret management services (AWS Secrets Manager, etc.)
    ✅ Configuration injection at runtime

  Detection: Pre-push guard scans for secret patterns

Enforcement:

• Generation time: All agents avoid secrets in generated docs
• Edit time: constitution-guardian guardrail blocks save (this skill)
• Pre-push: Git pre-push hook scans for secrets

Skip Conditions

Users can bypass Constitution guardian in specific scenarios:

1. Session Skip (One-time per session)

• Mechanism: sessionSkillUsed: true in skill-rules.json
• Behavior: Guardrail only triggers once per Claude session
• Use case: User acknowledged violation, working on fix

2. File Marker (Permanent skip for specific file)

• Marker: Add @constitution-verified comment in document
• Example:

``markdown <!-- @constitution-verified: Legacy doc migration, compliance review completed --> ``

• Use case: Legacy documentation, special cases

3. Environment Variable (Temporary global skip)

• Variable: SKIP_CONSTITUTION_CHECK=1
• Scope: Current terminal session
• Use case: Bulk imports, automated migrations

Relationship with Other Components

validate-constitution.sh (Script)

• Purpose: Batch validation of all 10 Constitutional Articles
• Scope: Complete document/codebase scan
• Timing: Phase completion (e.g., /flow-prd Exit Gate)
• Articles: I, II, III, IV, V, VI, VII, VIII, IX, X

constitution-guardian (Guardrail)

• Purpose: Real-time prevention of critical violations
• Scope: Single document being edited
• Timing: During file editing (PreToolUse hook)
• Articles: Focus on I.1, III.1 (most critical for documents)

Relationship: Complementary (互补)

• Guardrail: Real-time prevention (write-time, partial Articles)
• Script: Batch validation (phase-time, all Articles)
• Double insurance: Guardrail catches most issues, Script catches remaining

Constitution Document

• Source of Truth: .claude/rules/project-constitution.md v2.0.0
• Contains: All 10 Articles with detailed rules
• This guardrail: Extracts Articles I.1, III.1 prohibition rules only

Configuration

In .claude/skills/skill-rules.json:

{
  "constitution-guardian": {
    "type": "guardrail",
    "enforcement": "block",
    "priority": "critical",
    "description": "Real-time Constitution compliance, extracted from Constitution v2.0.0",
    "fileTriggers": {
      "pathPatterns": [
        "devflow/requirements/**/PRD.md",
        "devflow/requirements/**/EPIC.md",
        "devflow/requirements/**/TASKS.md",
        "devflow/requirements/**/TECH_DESIGN.md",
        "devflow/requirements/**/contracts/**/*.yaml",
        "devflow/requirements/**/data-model.md"
      ],
      "contentPatterns": [
        "TODO.*later",
        "FIXME",
        "\\[placeholder\\]",
        "simplified for now",
        "defer to v\\d",
        "API_KEY\\s*=\\s*['\"]?[a-zA-Z0-9_-]{10,}",
        "SECRET\\s*=\\s*['\"]?[a-zA-Z0-9_-]+",
        "PASSWORD\\s*=\\s*['\"]?[^\\s]+",
        "TOKEN\\s*=\\s*['\"]?[a-zA-Z0-9_-]{10,}",
        "apiKey:\\s*['\"][^'\"]+['\"]",
        "password:\\s*['\"][^'\"]+['\"]"
      ]
    },
    "blockMessage": "⚠️ BLOCKED - Constitution Violation\n\nDetected:\n- Partial implementation (Article I.1)\n- Hardcoded secrets (Article III.1)\n\n📋 ACTION:\n1. Complete all TODOs/FIXMEs\n2. Move secrets to config system\n3. Run /flow-verify\n\nSource: .claude/rules/project-constitution.md v2.0.0",
    "skipConditions": {
      "sessionSkillUsed": true,
      "fileMarkers": ["@constitution-verified"],
      "envOverride": "SKIP_CONSTITUTION_CHECK"
    }
  }
}

Line Number Reporting (Enhancement)

Goal: Precise violation location reporting

Implementation (in PreToolUse hook):

function detectViolations(content: string, patterns: string[]) {
  const lines = content.split('\n');
  const violations: Array<{line: number, pattern: string, text: string}> = [];

  lines.forEach((line, index) => {
    patterns.forEach(pattern => {
      if (new RegExp(pattern, 'i').test(lin