mcp-ai-agent-guidelines
Version:
A comprehensive Model Context Protocol server providing professional tools, resources, and prompts for implementing AI agent best practices
495 lines (476 loc) • 22.7 kB
JavaScript
// Cross-Session Constraint Consistency Enforcer
// Validates constraint usage and documentation across design sessions for alignment with Space 7 Instructions and templates
import { z } from "zod";
import { logger } from "../shared/logger.js";
import { adrGenerator } from "./adr-generator.js";
import { constraintManager, } from "./constraint-manager.js";
// Schema for persistence
const _ConstraintEnforcementHistorySchema = z.object({
constraintId: z.string(),
sessionId: z.string(),
timestamp: z.string(),
phase: z.string(),
decision: z.string(),
rationale: z.string(),
enforcement: z.boolean(),
violation: z.string().optional(),
resolution: z.string().optional(),
context: z.string(),
});
class ConstraintConsistencyEnforcerImpl {
enforcementHistory = new Map();
initialized = false;
async initialize() {
// Always reset in-memory history to avoid cross-test leakage
this.enforcementHistory = new Map();
if (this.initialized)
return;
try {
// Load any persisted enforcement history
await this.loadEnforcementHistory();
this.initialized = true;
}
catch (error) {
throw new Error(`Failed to initialize Constraint Consistency Enforcer: ${error instanceof Error ? error.message : "Unknown error"}`);
}
}
/**
* Enforce cross-session constraint consistency
*/
async enforceConsistency(request) {
await this.initialize();
// Backwards-compat: allow passing sessionState directly
const reqObj = request;
const isSessionOnly = request &&
typeof request === "object" &&
!("sessionState" in reqObj) &&
("config" in reqObj || "currentPhase" in reqObj);
const sessionState = (isSessionOnly
? request
: request.sessionState);
const constraintId = isSessionOnly
? undefined
: request.constraintId;
const phaseId = isSessionOnly
? undefined
: request.phaseId;
const context = isSessionOnly
? ""
: (request.context ?? "");
const strictMode = isSessionOnly
? false
: (request.strictMode ?? false);
// Validate constraints for current session
const currentValidation = constraintManager.validateConstraints(sessionState, constraintId ? [constraintId] : undefined);
// Perform cross-session validation
const crossSessionValidation = await this.validateCrossSessionConsistency(sessionState, constraintId);
// Generate enforcement actions based on validation results
const enforcementActions = this.generateEnforcementActions(currentValidation, crossSessionValidation, strictMode);
// Generate interactive prompts for user validation
const interactivePrompts = this.generateInteractivePrompts(crossSessionValidation, phaseId || sessionState.currentPhase);
// Generate artifacts (ADRs, specs) for enforcement decisions
const generatedArtifacts = await this.generateEnforcementArtifacts(sessionState, crossSessionValidation, enforcementActions);
// Store enforcement decisions for future consistency checks
await this.storeEnforcementDecisions(sessionState, enforcementActions, context);
// Calculate consistency score
const consistencyScore = this.calculateConsistencyScore(crossSessionValidation);
return {
success: crossSessionValidation.passed,
consistencyScore,
enforcementActions,
generatedArtifacts,
interactivePrompts,
recommendations: [
...currentValidation.recommendations,
...crossSessionValidation.recommendations,
],
historicalAlignments: this.generateHistoricalAlignments(crossSessionValidation),
};
}
/**
* Backwards-compatible wrapper: detect violations for a session
*/
async detectViolations(request) {
await this.initialize();
const reqObj = request;
const isSessionOnly = request && typeof request === "object" && !("sessionState" in reqObj);
const sessionState = (isSessionOnly
? request
: request.sessionState);
const constraintId = isSessionOnly
? undefined
: request
.constraintId;
const result = await this.validateCrossSessionConsistency(sessionState, constraintId);
return result.violations;
}
/**
* Backwards-compatible wrapper: generate a simple string report
*/
async generateReport(request) {
await this.initialize();
const reqObj = request;
const isSessionOnly = request && typeof request === "object" && !("sessionState" in reqObj);
const sessionState = (isSessionOnly
? request
: request.sessionState);
const constraintId = isSessionOnly
? undefined
: request
.constraintId;
const validation = await this.validateCrossSessionConsistency(sessionState, constraintId);
const lines = [
`Cross-Session Constraint Consistency Report for ${sessionState?.config?.sessionId || "unknown-session"}`,
`Consistency Score: ${validation.consistencyScore}%`,
`Violations: ${validation.violations.length}`,
];
if (validation.violations.length > 0) {
lines.push("Details:");
for (const v of validation.violations.slice(0, 5)) {
lines.push(`- [${v.severity}] ${v.constraintId}: ${v.description}`);
}
}
return lines.join("\n");
}
/**
* Validate constraint consistency across previous sessions
*/
async validateCrossSessionConsistency(sessionState, constraintId) {
const violations = [];
const recommendations = [];
const enforcementActions = [];
// Get constraints to validate
const constraintsToCheck = constraintId
? [constraintManager.getConstraint(constraintId)].filter(Boolean)
: constraintManager.getMandatoryConstraints();
// Get historical context for comparison
const historicalContext = this.getRelevantHistory(sessionState, constraintId);
for (const constraint of constraintsToCheck) {
if (!constraint)
continue; // Skip undefined constraints
const constraintHistory = historicalContext.filter((h) => h.constraintId === constraint.id);
if (constraintHistory.length === 0) {
// No previous history - first time using this constraint
recommendations.push(`First usage of constraint "${constraint.name}". Consider establishing baseline rationale.`);
continue;
}
// Check for decision conflicts
const decisions = constraintHistory.map((h) => h.decision);
const uniqueDecisions = [...new Set(decisions)];
if (uniqueDecisions.length > 1) {
violations.push({
constraintId: constraint.id,
currentSessionId: sessionState.config.sessionId,
conflictingSessionId: constraintHistory[0].sessionId,
violationType: "decision_conflict",
description: `Conflicting decisions found for constraint "${constraint.name}": ${uniqueDecisions.join(" vs ")}`,
severity: constraint.mandatory ? "critical" : "warning",
suggestedResolution: "Review previous decisions and align approach or document rationale for deviation",
});
enforcementActions.push({
id: `conflict-${constraint.id}`,
type: "prompt_for_clarification",
constraintId: constraint.id,
description: `Resolve decision conflict for ${constraint.name}`,
interactive: true,
prompt: this.generateConflictResolutionPrompt(constraint, constraintHistory),
expectedOutcome: "Alignment with previous decisions or documented deviation rationale",
});
}
// Check for enforcement consistency
const enforcementPatterns = constraintHistory.map((h) => h.enforcement);
const inconsistentEnforcement = enforcementPatterns.some((e) => e !== enforcementPatterns[0]);
if (inconsistentEnforcement) {
violations.push({
constraintId: constraint.id,
currentSessionId: sessionState.config.sessionId,
conflictingSessionId: constraintHistory.find((h) => h.enforcement !== enforcementPatterns[0])?.sessionId || "",
violationType: "enforcement_mismatch",
description: `Inconsistent enforcement pattern for constraint "${constraint.name}"`,
severity: "warning",
suggestedResolution: "Establish consistent enforcement approach across sessions",
});
}
}
const passed = violations.filter((v) => v.severity === "critical").length === 0;
const consistencyScore = this.calculateRawConsistencyScore(violations, constraintsToCheck.length);
return {
passed,
consistencyScore,
violations,
recommendations,
enforcementActions,
historicalContext,
};
}
/**
* Generate enforcement actions based on validation results
*/
generateEnforcementActions(currentValidation, crossSessionValidation, strictMode) {
const actions = [];
// Add cross-session enforcement actions
actions.push(...crossSessionValidation.enforcementActions);
// Add current session enforcement actions based on violations
for (const violation of currentValidation.violations) {
if (violation.severity === "error" ||
(strictMode && violation.severity === "warning")) {
actions.push({
id: `current-${violation.constraintId}`,
type: "prompt_for_clarification",
constraintId: violation.constraintId,
description: `Address current session violation: ${violation.message}`,
interactive: true,
prompt: this.generateViolationResolutionPrompt(violation),
expectedOutcome: "Constraint compliance or documented exception",
});
}
}
// Generate ADR actions for significant enforcement decisions
const significantActions = actions.filter((a) => a.type === "prompt_for_clarification");
if (significantActions.length > 0) {
actions.push({
id: "enforcement-adr",
type: "generate_adr",
constraintId: "enforcement-decisions",
description: "Document constraint enforcement decisions",
interactive: false,
expectedOutcome: "ADR documenting enforcement rationale and decisions",
});
}
return actions;
}
/**
* Generate interactive validation prompts
*/
generateInteractivePrompts(crossSessionValidation, phaseId) {
const prompts = [];
// Generate prompts for critical violations
const criticalViolations = crossSessionValidation.violations.filter((v) => v.severity === "critical");
for (const violation of criticalViolations) {
prompts.push(this.generateContextDrivenPrompt(violation, phaseId));
}
// Add Space 7 alignment prompts if needed
if (crossSessionValidation.consistencyScore < 80) {
prompts.push(this.generateSpace7AlignmentPrompt(phaseId, crossSessionValidation));
}
return prompts;
}
/**
* Generate enforcement artifacts (ADRs, specs, etc.)
*/
async generateEnforcementArtifacts(sessionState, crossSessionValidation, enforcementActions) {
const artifacts = [];
// Generate ADRs for enforcement decisions
const adrActions = enforcementActions.filter((a) => a.type === "generate_adr");
for (const action of adrActions) {
try {
const adrResult = await adrGenerator.generateADR({
sessionState,
title: `Constraint Enforcement Decision: ${action.description}`,
context: `Cross-session constraint consistency enforcement for ${sessionState.config.context}`,
decision: this.generateEnforcementDecisionText(crossSessionValidation, enforcementActions),
consequences: this.generateEnforcementConsequences(crossSessionValidation),
status: "accepted",
metadata: {
consistencyScore: crossSessionValidation.consistencyScore,
violationsCount: crossSessionValidation.violations.length,
enforcementType: "cross-session-consistency",
},
});
artifacts.push(adrResult.artifact);
}
catch (error) {
// Continue with other artifacts if ADR generation fails
logger.warn("Failed to generate enforcement ADR", {
error: error instanceof Error ? error.message : "Unknown error",
sessionId: sessionState.config.sessionId,
phase: sessionState.currentPhase,
});
}
}
return artifacts;
}
/**
* Store enforcement decisions for future consistency checks
*/
async storeEnforcementDecisions(sessionState, enforcementActions, context) {
const timestamp = new Date().toISOString();
const sessionId = sessionState.config.sessionId;
const phase = sessionState.currentPhase;
for (const action of enforcementActions) {
const history = {
constraintId: action.constraintId,
sessionId,
timestamp,
phase,
decision: action.description,
rationale: action.expectedOutcome || "Automated enforcement action",
enforcement: true,
context,
};
// Store in memory (in production, this would persist to disk/database)
const constraintHistory = this.enforcementHistory.get(action.constraintId) || [];
constraintHistory.push(history);
this.enforcementHistory.set(action.constraintId, constraintHistory);
}
// Persist to storage (mock implementation)
await this.persistEnforcementHistory();
}
/**
* Calculate consistency score based on validation results
*/
calculateConsistencyScore(crossSessionValidation) {
return crossSessionValidation.consistencyScore;
}
calculateRawConsistencyScore(violations, totalConstraints) {
if (totalConstraints === 0)
return 100;
const criticalViolations = violations.filter((v) => v.severity === "critical").length;
const warningViolations = violations.filter((v) => v.severity === "warning").length;
// Critical violations have more impact
const violationScore = criticalViolations * 10 + warningViolations * 3;
const maxScore = totalConstraints * 10;
return Math.max(0, Math.round(((maxScore - violationScore) / maxScore) * 100));
}
/**
* Get relevant constraint enforcement history
*/
getRelevantHistory(sessionState, constraintId) {
const allHistory = [];
if (constraintId) {
const constraintHistory = this.enforcementHistory.get(constraintId) || [];
allHistory.push(...constraintHistory);
}
else {
// Get history for all constraints used in current session
const constraints = sessionState?.config?.constraints || [];
for (const constraint of constraints) {
const constraintHistory = this.enforcementHistory.get(constraint.id) || [];
allHistory.push(...constraintHistory);
}
}
// Filter out current session to get cross-session history
const currentSessionId = sessionState?.config?.sessionId;
return currentSessionId
? allHistory.filter((h) => h.sessionId !== currentSessionId)
: allHistory;
}
/**
* Generate context-driven validation prompts
*/
generateContextDrivenPrompt(violation, phaseId) {
const phaseContext = this.getPhaseContext(phaseId);
return `## Constraint Consistency Validation Required
**Phase**: ${phaseContext.name}
**Constraint**: ${violation.constraintId}
**Issue**: ${violation.description}
**Previous Sessions Context**:
Sessions with conflicting approaches have been detected. This may indicate:
1. Evolution in requirements or understanding
2. Different project contexts requiring different approaches
3. Inconsistent application of guidelines
**Resolution Options**:
1. **Align with Previous**: ${violation.suggestedResolution}
2. **Document Deviation**: Provide rationale for why this session requires a different approach
3. **Update Guidelines**: If this represents an improved approach, consider updating the constraint definition
**Space 7 Guidance**: ${this.getSpace7GuidanceForConstraint(violation.constraintId)}
Please specify your approach and rationale:`;
}
/**
* Generate Space 7 alignment prompts
*/
generateSpace7AlignmentPrompt(phaseId, crossSessionValidation) {
const phaseContext = this.getPhaseContext(phaseId);
return `## Space 7 Instructions Alignment Check
**Current Phase**: ${phaseContext.name}
**Consistency Score**: ${crossSessionValidation.consistencyScore}%
Based on Space 7 General Instructions and design process templates, please verify:
1. **Phase Coverage**: Are all required outputs for ${phaseContext.name} being addressed consistently?
2. **Constraint Application**: Are constraints being applied uniformly across sessions?
3. **Documentation Standards**: Is rationale being documented according to Space 7 guidelines?
**Template References**:
${this.getRelevantTemplateReferences(phaseId)
.map((ref) => `- ${ref}`)
.join("\n")}
**Recommendations**:
${crossSessionValidation.recommendations.map((rec) => `- ${rec}`).join("\n")}
Please confirm alignment or document deviations:`;
}
/**
* Generate conflict resolution prompts
*/
generateConflictResolutionPrompt(constraint, history) {
return `## Constraint Decision Conflict Resolution
**Constraint**: ${constraint.name}
**Description**: ${constraint.description}
**Previous Decisions**:
${history.map((h, i) => `${i + 1}. Session ${h.sessionId} (${h.phase}): ${h.decision}\n Rationale: ${h.rationale}`).join("\n")}
**Current Session Context**: Please specify how this constraint should be applied in the current context.
**Options**:
1. **Follow Previous Pattern**: Adopt the same approach as previous sessions
2. **Justify Deviation**: Explain why current context requires different approach
3. **Escalate**: Flag for broader team discussion if constraint definition needs clarification
Your decision and rationale:`;
}
/**
* Generate violation resolution prompts
*/
generateViolationResolutionPrompt(violation) {
return `## Constraint Violation Resolution
**Constraint**: ${violation.constraintId}
**Violation**: ${violation.message}
**Suggested Fix**: ${violation.suggestion}
Please address this violation by:
1. Implementing the suggested fix
2. Providing rationale for acceptable deviation
3. Requesting constraint modification if inappropriate
Your resolution:`;
}
/**
* Helper methods
*/
getPhaseContext(phaseId) {
const phaseRequirements = constraintManager.getPhaseRequirements(phaseId);
return (phaseRequirements || { name: phaseId, description: `${phaseId} phase` });
}
getSpace7GuidanceForConstraint(constraintId) {
const constraint = constraintManager.getConstraint(constraintId);
return (constraint?.source ||
"Refer to Space 7 General Instructions for constraint guidance");
}
getRelevantTemplateReferences(_phaseId) {
const templateRefs = constraintManager.getTemplateReferences();
return Object.values(templateRefs).slice(0, 3); // Return first 3 relevant templates
}
generateEnforcementDecisionText(crossSessionValidation, enforcementActions) {
return `Cross-session constraint consistency enforcement resulted in ${enforcementActions.length} enforcement actions with ${crossSessionValidation.violations.length} violations detected. Consistency score: ${crossSessionValidation.consistencyScore}%.`;
}
generateEnforcementConsequences(crossSessionValidation) {
const consequences = [
`Improved constraint consistency across design sessions`,
`${crossSessionValidation.violations.length} consistency issues identified and addressed`,
];
if (crossSessionValidation.consistencyScore < 70) {
consequences.push("May require additional review and alignment of constraint application patterns");
}
return consequences.join("; ");
}
generateHistoricalAlignments(crossSessionValidation) {
return crossSessionValidation.historicalContext.map((h) => `${h.constraintId}: ${h.decision} (${h.sessionId})`);
}
/**
* Persistence methods (mock implementation - in production would use file system or database)
*/
async loadEnforcementHistory() {
// Mock implementation - in production, load from persistent storage
// For now, start with empty history
}
async persistEnforcementHistory() {
// Mock implementation - in production, save to persistent storage
// Could save to JSON files, database, etc.
}
}
export const constraintConsistencyEnforcer = new ConstraintConsistencyEnforcerImpl();
// Module Implementation Status Sentinel
export const IMPLEMENTATION_STATUS = "IMPLEMENTED";
//# sourceMappingURL=constraint-consistency-enforcer.js.map