agile-constitution-check

name	agile-constitution-check
description	Validates artifacts against the GSB Federated Constitution Architecture. Detects affected domains from artifact content, loads relevant constitutions (master + domain-specific), and checks principle ID references for compliance. Used by epic and feature journey commands as a compliance gate.
user-invocable	false
disable-model-invocation	false

Agile Constitution Check

Background compliance validator for journey artifacts (specs, plans, epics) against the GSB Federated Constitution Architecture.

Constitution Architecture

The GSB project uses a federated constitution system:

Master Constitution (.agile/rules/constitution.md)
    ├── .agile/rules/common/constitution.md    (common/)
    ├── .agile/rules/workers/constitution.md   (workers/)
    ├── .agile/rules/frontend/constitution.md  (frontend/)
    └── .agile/rules/services/constitution.md  (services/)

• Master principles (MASTER:I-XIV) apply to ALL domains and cannot be overridden
• Domain principles extend master principles with domain-specific requirements
• Epic governance principles (EPIC:I-III) apply to epic-level artifacts
• Cross-domain features apply ALL relevant domain constitutions

Domain Detection

Automatically identify affected domains from artifact content:

Content Pattern	Domain	Constitution
workers/**, batch, GSBBatch	WORKER	.agile/rules/workers/constitution.md
frontend/**, React, TypeScript, component	FRONTEND	.agile/rules/frontend/constitution.md
services/**, microservice, API, endpoint	SERVICES	.agile/rules/services/constitution.md
common/**, entity, repository, shared	COMMON	.agile/rules/common/constitution.md
Cross-domain or undetected	MASTER only	.agile/rules/constitution.md

Detection sources:

1. File paths referenced in the artifact
2. Directory patterns mentioned in scope sections
3. Technology keywords (React, Spring Boot, MapDB, etc.)
4. Module references (services/core, workers/batch, frontend/src)

Use scripts/constitution-detect.sh for automated domain detection from paths.

Validation Process

1. Detect affected domains from artifact content (paths, keywords, scope)
2. Load master constitution (always applied) + relevant domain constitutions
3. Check principle ID references -- verify artifact references correct IDs (format: {DOMAIN}:{ROMAN_NUMERAL})
4. Identify missing references -- flag principles that should be present based on domain and artifact type
5. Flag violated principles -- detect content that contradicts constitution requirements
6. Generate compliance report with findings and recommendations

Principle ID Format

All principle IDs follow the pattern {DOMAIN}:{ROMAN_NUMERAL}:

• Master: MASTER:I through MASTER:XIV
• Worker: WORKER:I through WORKER:XIII
• Frontend: FRONTEND:I through FRONTEND:XVIII
• Services: SERVICES:I through SERVICES:XVII
• Common: COMMON:I through COMMON:XI
• Epic: EPIC:I through EPIC:III

See references/principle-index.md for the full catalog with titles.

Compliance Report Output

The validation produces a structured report:

## Constitution Compliance Report

**Artifact**: [path/to/artifact]
**Detected Domains**: [MASTER, WORKER, ...]
**Status**: COMPLIANT | PARTIAL | NON-COMPLIANT

### Compliant Principles
- MASTER:V -- Naming Standards (referenced correctly)
- WORKER:I -- Performance-First Design (addressed in spec)

### Missing References
- WORKER:VI -- Testing Discipline (no testing section found)
- MASTER:III -- Testing Requirements (should be present)

### Violated Principles
- MASTER:V -- Found abbreviation "cust" instead of "customers"

### Recommendations
- Add testing strategy section to address WORKER:VI
- Replace abbreviated terms per MASTER:V mapping table

Integration Points

This skill is called by journey commands as a compliance gate:

• create.md -- Validates new artifact structure and required principle references
• plan.md -- Checks implementation plans reference applicable principles
• validate.md -- Full compliance validation before artifact finalization

Validation Scripts

Automated validation helpers in scripts/:

Script	Purpose
constitution-detect.sh	Domain detection from file paths and content
validate-constitution-versions.sh	Verify constitution file versions match index
validate-principle-counts.sh	Verify principle counts match index registry

Key Validation Rules

1. Master principles always apply -- Every artifact must account for relevant MASTER principles
2. Domain detection drives scope -- Only domain-specific principles for detected domains are checked
3. Cross-domain = all domains -- Artifacts touching multiple domains must satisfy all applicable constitutions
4. Precedence: Master > Domain -- If domain principle conflicts with master, master wins
5. Naming standard (MASTER:V) is checked in all artifacts -- no abbreviations in identifiers or docs
6. Testing requirements (MASTER:III) must be addressed in implementation plans and specs

Constitution File Locations

All constitutions reside in .agile/rules/:

File	Domain	Current Version
.agile/rules/constitution.md	Master	1.9.2
.agile/rules/workers/constitution.md	Worker	2.5.1
.agile/rules/frontend/constitution.md	Frontend	1.1.0
.agile/rules/services/constitution.md	Services	1.10.0
.agile/rules/common/constitution.md	Common	1.3.0

Always read the actual constitution files for full principle text. The references/principle-index.md provides a quick-reference catalog only.