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:

<!-- @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